Substack MCP

What conorbronsdon/substack-mcp MCP server does

The conorbronsdon/substack-mcp MCP server connects an MCP-compatible AI client to a Substack publication. Its read operations cover published posts, drafts, comments, sections, scheduled posts, subscriber counts, and post-level analytics. Full post and draft content includes fields such as title, body, and metadata, while list operations provide publication records with pagination where supported.

Long-form content changes remain draft-only. An agent can create a new draft from Markdown or update an unpublished draft, but it cannot publish, delete, or schedule a long-form post. Scheduling remains an action performed in Substack’s editor. The server can read posts already scheduled there with their IDs, titles, audiences, and scheduled times.

The exception is Substack Notes. create_note and create_note_with_link publish short-form content directly to the public Notes feed because Substack does not provide a draft state for Notes. These operations have no preview or undo through the server.

How it works

The server communicates with Substack using publication credentials supplied through environment variables or a locally stored browser-login session. Requests are scoped to a publication, and the configuration can support more than one publication by defining a separate URL, session token, and user ID triplet for each one.

Post analytics require a lookup rather than a dedicated per-post statistics endpoint. The server searches the 500 most recent published posts for the requested ID and reports a not-found result when the post is outside that range. Subscriber results include a precision indicator: exact, approximate, or unavailable. Approximate values should be displayed as lower-bound-style figures such as “1,000+,” not as exact counts.

Image uploads accept either a base64 data URI or a local file path, but not both. The returned Substack CDN URL is publicly fetchable by anyone with the link, although the asset is unlisted and is not attributed to the publication feed.

Setup and configuration

The conorbronsdon/substack-mcp MCP server is available from npm as @conorbronsdon/substack-mcp. A client can run it with npx -y @conorbronsdon/substack-mcp and provide SUBSTACK_PUBLICATION_URL, SUBSTACK_SESSION_TOKEN, and SUBSTACK_USER_ID in the MCP server environment.

As an alternative, the optional login command opens Chromium through Playwright, captures the Substack session cookie, resolves the user ID, and stores an encrypted session file under ~/.substack-mcp/session.json. SUBSTACK_MCP_HOME can change that directory. Playwright must be installed separately. When the stored session is available and the credential environment variables are unset, the MCP server reads the session file automatically.

Claude Desktop configuration uses a server entry with the npm runner and those environment variables. The repository also documents Claude Code configuration. Browser login storage is machine-bound and encrypted, but it is not a substitute for a secret vault.

Tools and capabilities

The available operations include:

• Count publication subscribers with an explicit precision status.
• List and retrieve published posts and drafts.
• Read post comments, sections, scheduled posts, and performance statistics.
• Create or revise unpublished drafts from Markdown.
• Upload an image and receive a hosted CDN URL.
• Publish a Note immediately, optionally with a link card.

The tools declare read-only and non-destructive annotations where applicable, but tool annotations are hints. The tool descriptions and the actual behavior are authoritative, especially for Note publishing and public image URLs.

Limitations and notes

The conorbronsdon/substack-mcp MCP server does not provide long-form publishing, deletion, or scheduling controls. Draft updates only work for unpublished drafts. Notes are public immediately and cannot be reverted through this server. Uploaded images are publicly retrievable by URL, so agents should avoid treating them as private files. A copied browser session file is protected against casual inspection and use on another machine, but code running under the same operating-system account may still be able to re-derive its key.