conorbronsdon/substack-mcp

Create and manage your Substack newsletter from your AI assistant or terminal. Prepare rich drafts, search your archive, publish Notes, inspect analytics, and manage explicitly consented free subscribers across publications. Review and publish long-form posts in Substack.
---
The demo runs actual MCP handlers against offline sample data. No live API calls or publication occur. Follow the draft workflow to create, find, export and review a post.
**Safe by design — with one loud exception:** This server cannot publish or delete long-form posts. Post tools create and edit drafts only; you review and publish manually through Substack's editor. The exception is Substack **Notes**: create_note and create_note_with_link publish short-form Notes immediately, because Notes have no draft state on Substack. Treat the Note tools as public-publish actions — there is no preview step and no undo from this server. The split is proportionate review, the piece of trust infrastructure for agents this server cares most about: the high-stakes surface gets a human gate, and the exception is stated loudly.
This server imposes no Bestseller-status check. Use an authenticated account with permission to manage the publication; individual operations depend on your Substack access. Connect through local stdio or self-hosted HTTP.
For 1.0 setup coverage and account eligibility, see compatibility. Maintainers can use the release checklist and distribution inventory.
**Contents:** Quick start · Setup · Tools · Operator CLI · Draft workflow · Analytics to draft · Export · Markdown · Multiple publications · Transports · Compatibility
Quick start
1. **Install and sign in.** Browser login needs the optional Playwright dependency:
Use your own account's user ID (how to find it). The session is saved only after a bounded
authenticated read succeeds. To paste credentials instead, see
Option B.
2. **Verify a read.** npx substack-mcp doctor --json --check-auth makes one
bounded read per publication. It confirms read access, not your user ID or
write permission.
3. **Connect your MCP client.** Add the server to
Claude Desktop or Claude Code, or use the
Codex plugin. Environment variables take precedence; omit
them to use the stored browser-login session. Then ask your assistant:
"How many Substack subscribers do I have?"
4. **Prepare a draft for review.** Follow the draft workflow:
create_draft, search_posts, export_draft, preflight_draft, then
plan_draft_update and update_draft. Long-form posts stay unpublished
drafts until you publish them in Substack's editor. create_note and
create_note_with_link publish immediately.
Community walkthrough
Jonathan Price's I used Codex to connect ChatGPT to Substack. Then it drafted this post.
walks through using Codex to install the MCP locally, connecting ChatGPT through
OpenAI's Secure MCP Tunnel, and creating a private draft for manual publication.
He used the connection to create the draft of the guide itself.
The guide documents his September 18, 2026 setup with version 1.2.0. Its reported
get_post 404 is fixed in 1.2.1. Client interfaces and access requirements can
change; use the setup instructions below for this package's current
configuration. This is a community walkthrough, not a hosted service provided
by this project.
Setup
Requires **Node.js 22 or newer** (CI covers Node 22 and 24). Browser login additionally requires Playwright.
You can supply credentials two ways: paste them as env vars (below), or run the
optional **browser login** which captures and stores them for you.
Option A — Browser login (optional, no manual cookie copying)
Install the server and optional Playwright dependency together in a local tools
directory, then sign in:
substack-mcp-login remains a supported alias. Missing publication URL and user
ID are prompted. Supply your own account's user ID (steps below); a post author's byline does
not verify your identity. The browser opens for sign-in, including any CAPTCHA.
Login then opens /publish/home and waits for the publication
session cookie; on custom domains this is connect.sid on the custom domain.
A bounded authenticated read must succeed before saving. This verifies read access, not
the configured user ID or permission to write.
Without --profile, login saves ~/.substack-mcp/session.json (directory override:
SUBSTACK_MCP_HOME). The server uses this legacy session when publication
credential environment variables and SUBSTACK_PROFILES are unset.
**Default storage (SUBSTACK_CREDENTIAL_STORE=file):** sessions use AES-256-GCM with a key derived from the OS account and