Substack API + MCP (2026): official read-only MCP, no write API

Substack shipped an official MCP server before it shipped a usable REST API. Since July 6, 2026 an admin of a Bestseller publication can connect Claude or ChatGPT to a first-party, read-only endpoint and pull dashboard metrics into a chat, while the same admin still has no documented way to publish a post, add a subscriber or send an email programmatically. The official Developer API exists, but its Terms of Use scope it to publicly visible creator profile data behind manual approval, and Substack publishes zero official SDKs. Read this tab as a constraints document, not an integration guide.

At a glance

MCP integration in 2026

Model Context Protocol is the one developer-adjacent area where Substack moved early. The company announced MCP support on July 6, 2026, describing it as a way for bestsellers to “understand your publication stats by integrating with tools like Claude and ChatGPT”. What it is not is a write channel.

Available MCP servers

One official server, five community servers with meaningfully different risk profiles. The community projects all drive undocumented internal endpoints or a copied browser session token, none is sanctioned, and the session-token pattern hands the MCP process the practical equivalent of your password.

Substack API essentials

One official API surface exists and it is deliberately narrow. The Substack Developer API is governed by Terms of Use last updated January 8, 2026, which scope it to “Authorized Data”, publicly visible creator profile information such as names, social URLs, subscriber counts and profile summaries. Access is granted by manual application. Substack publishes no developer reference with a base URL, version string, request contract or pagination scheme, so the table below records what is documented and marks the rest as unpublished rather than filling gaps from community packages.

The practical consequence is that the RSS feed, not the API, is the only stable read interface most developers will ever use against Substack. It needs no key, it is a product feature rather than a developer contract, and it survives platform changes because subscribers and podcast apps depend on it. Everything richer than “what did this publication publish, and when” needs the approval-gated profile API, the Bestseller-gated MCP server, or an unsupported wrapper that will break.

Authentication methods

Two authorisation paths exist officially, and they are entirely separate systems. Neither issues a credential you can create yourself in a dashboard, which is the first structural difference a developer coming from beehiiv or Kit will notice.

Developer API credentials

Access is granted through a manual application. Substack publishes no credential format, header name or token lifetime, so no example request can be written here without inventing it. What the Terms of Use do state is the boundary on a granted credential: you may not derive non-public attributes about creators, aggregate the data for profiling, redistribute it as a standalone product, build features that compete with Substack, or use it for unsolicited communications. Plan approval as a dependency with unknown turnaround, not a formality.

MCP account authorisation

The official MCP server uses an OAuth-style consent flow inside the AI client rather than a static key. In Claude you add it under Customize › Connectors › Add custom connector, point it at https://mcp.substack.com/api/v1/mcp, sign into Substack in the window that opens and grant read permission on a publication you administer. Revocation happens on the Substack side, not by rotating a secret.

Session tokens used by community tools

Most community MCP servers and SDKs ask you to copy a session cookie out of your browser into a config file. This is not an authentication method Substack offers; it is an impersonation of your logged-in browser.

Rate limits

Substack publishes no numeric limit of any kind, for the API or for sending. That is the documented position, not a research gap: the Developer API Terms of Use state only that “Your use of the API is subject to rate limits, quotas, and other technical restrictions as determined by Substack in its sole discretion”.

The workaround is architectural rather than technical, because there is no quota to negotiate up. If your integration reads, build it on the RSS feed and cache aggressively: poll on a schedule measured in minutes, store last-seen GUIDs, and never fan out per-item requests against publication URLs. If it writes, accept that no supported path exists and move the write side to a platform that documents one – beehiiv, Kit, MailerLite and Flodesk all expose a sending or subscriber API with stated behaviour. For a large migration in either direction, budget slack for the human review step rather than assuming an overnight cutover.

Official SDKs

There are none. Substack publishes no client library, no OpenAPI description and no public engineering repositories, in any language, as of 2026. Every package on npm, PyPI or CRAN carrying the Substack name is community-built and wraps undocumented internal endpoints or an authenticated session.

Notable community SDKs

Three community clients are maintained well enough to be worth naming. All three read public or semi-public data; none can send an email, and none carries a support commitment. Pin a commit, read the code before you run it, and assume the interface it wraps can change without notice.

The Python wrapper reads publications, posts and user profiles; the TypeScript client offers an entity-based interface over publications, posts, comments and profiles. substackR is the only one distributed through a curated registry, which raises the floor on packaging quality but says nothing about the endpoints underneath. None should sit on the critical path of a production system.

Endpoints reference

A conventional endpoint table cannot be written for Substack, because Substack documents no REST endpoints. What follows is the honest equivalent: the inventory of things a developer might want to do, and the officially documented surface for each. Third-party articles describe internal JSON paths that Substack’s own site calls; those are deliberately not listed, because they are unsupported and can change without notice. The authoritative references are the Developer API Terms of Use and the AI assistant help article.

Code examples

Two of the three snippets read the RSS feed, the only officially supported interface available without an approval process. The third connects the official MCP server. There is deliberately no send example: there is no Substack host, port, credential or endpoint to write one against.

Python, read a publication feed

# Substack documents no REST endpoints for sending, subscribers or posts.
# The only officially supported programmatic READ surface is the publication RSS feed.

import feedparser

FEED = "https://example.substack.com/feed"  # or https://yourdomain.com/feed on a custom domain

parsed = feedparser.parse(FEED)
print(parsed.feed.get("title"))

for entry in parsed.entries[:10]:
    print(entry.published, "|", entry.title)
    print(entry.link)

# There is deliberately no send() here: Substack exposes no relay and no send endpoint.
# To send mail yourself, export subscribers to CSV and use a provider with a relay.

Node.js, same read path

// Substack has no public send or subscriber API. The supported read path is the RSS feed.

import Parser from 'rss-parser';

const parser = new Parser();
const FEED = 'https://example.substack.com/feed'; // or https://yourdomain.com/feed

const feed = await parser.parseURL(FEED);
console.log(feed.title);

for (const item of feed.items.slice(0, 10)) {
  console.log(item.pubDate, '|', item.title);
  console.log(item.link);
}

// No nodemailer example is possible: there is no Substack SMTP host, port or credential.

MCP client configuration

// Remote MCP server, HTTP transport. Authorisation happens in the browser:
// you sign into Substack and grant read access on a publication you administer.
// Requires admin rights on a Bestseller publication - the server returns nothing otherwise.

{
  "mcpServers": {
    "substack": {
      "url": "https://mcp.substack.com/api/v1/mcp"
    }
  }
}

// In Claude: Customize -> Connectors -> Add custom connector -> paste the URL above.
// Operations are read-only: dashboard metrics, traffic data, publication settings.

Common gotchas

Deprecations and changelog

Substack maintains no developer changelog or API release-notes feed. The dates below come from the company’s own product announcements and from the Terms of Use, the only versioned developer-facing document the platform publishes.

• August 25, 2026 – Product release: creator match, audience-specific content blocks, global reply rules and advanced podcast transcript editing. No developer-facing surface added.
• July 6, 2026 – Official MCP support ships for Bestseller publications, alongside Subscriber Perks, saved Notes, scheduled Chats, polls and RSS support for externally hosted podcasts. Substack’s first first-party programmatic channel of any kind.
• April 8, 2026 – Product release: post templates, drop caps, scheduled Notes, callout blocks, a customisable subscribe homepage block and feed refinement controls.
• January 8, 2026 – Developer API Terms of Use last updated, formalising the API’s scope as publicly visible creator profile data only, with rate limits left to Substack’s sole discretion.
• October 21, 2020 – Custom domains launched at a one-time $50 fee per publication. Unchanged nearly six years later, and never extended to email sending.

Official release notes live at on.substack.com/archive, the API terms at substack.com/api-tos. Neither carries deprecation notices, because there is no versioned public API to deprecate.

Frequently asked questions