Substack MCP Server

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.

Draft-only long-form posts; explicit public actions: 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. Public community comments/restacks are separately experimental and consent-gated. Substack Notes also publish publicly: 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. Run substack-mcp compatibility report for an offline, shareable diagnostic report; reporting guide. 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:

   npm install @conorbronsdon/substack-mcp playwright

npx playwright install chromium npx substack-mcp login https://yourblog.substack.com --user-id 12345

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.

1. 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.
2. 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?"
3. 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:

npm install @conorbronsdon/substack-mcp playwright

npx playwright install chromium npx substack-mcp login https://yourblog.substack.com --user-id 12345

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. The default flow verifies read access, not the configured user ID or permission to write.

To derive your ID from the selected publication's authenticated session instead of entering it manually, use:

npx substack-mcp login https://yourblog.substack.com --verify-identity --profile work

--verify-identity reads the publication-host /api/v1/user/profile/self with that host's cookie, requires a positive safe integer top-level ID, and then performs the existing authenticated draft-list check before saving. Supplying --user-id as well turns it into an assertion: a mismatch stops without saving or replacing a profile, even with --force. No public profile, post byline, other-host cookie or other-host endpoint is used as a fallback. The verified mode's JSON result reports user_identity: "verified" and identity_source: "authenticated_publication_self_profile"; it prints no ID. This is an observation at login time, not a persisted identity attestation or proof of write permission. Ordinary doctor continues to report identity as unverified.

For subscriber tools or the calendar opt-in sync, add --subscriber-access. Substack asks for a one-time "Confirm it's you" code (by email or authenticator app) before it allows subscriber reads, and login prompts for it. See docs/subscriber-step-up.md.

Self-profile support on publication hosts has not been live-verified for every Substack/custom-domain configuration. If the endpoint is unavailable, expired, redirected or malformed, verified mode fails closed and saves nothing. The existing manually configured-ID flow remains available and explicitly unverified. A real browser run is still needed for #150; fixture tests are not evidence about the current sign-in UI.

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 machine. File permissions request 0600; Windows access also depends on directory ACLs. This is a machine-bound file, not an OS keychain or secret vault. Code running as your OS user can derive the key. Use environment credentials if your MCP client manages secrets for you.

Optional OS keychain: set SUBSTACK_CREDENTIAL_STORE=keychain in both the login process and the MCP client's environment. macOS uses Keychain via /usr/bin/security; Linux needs libsecret and secret-tool plus an unlocked Secret Service; Windows uses Credential Manager through PowerShell's PasswordVault. All three are exercised with synthetic credentials by the keychain CI workflow on GitHub-hosted runners (an unlocked temporary macOS keychain and a gnome-keyring session on Linux); desktop setups with locked keychains may still prompt. Login writes the selected account to the keychain, and the server reads it there. Explicit keychain selection never reads the encrypted file as a fallback. The keychain helps against other OS users, copied disks, and some malware limited to file access. Code running as your user can usually query the keychain. Keep the OS account and running code trusted. On Linux, secret-tool lookup can exit 1 without an error message for either an absent entry or a locked keyring. Named writes without --force search and unlock first, and refuse overwrites when an entry is found.

Named profiles and migration

npx substack-mcp login https://yourblog.substack.com --user-id 12345 --profile work

npx substack-mcp profiles list

Copy an existing legacy session without changing its file:

npx substack-mcp profiles migrate --name personal

Copy a file session or named file profile into the keychain; source remains:

npx substack-mcp profiles migrate --to keychain npx substack-mcp profiles migrate --to keychain --name work

Keys start with a lowercase ASCII letter and contain only lowercase letters, digits and hyphens, up to 64 characters. Existing profiles require explicit --force to replace. List output contains keys, readability status, publication origins and file save times; it excludes cookies and user IDs. Unreadable profiles remain visible but cannot be selected. Save time records local persistence, including migration; it is not token issuance or expiration time. Listing is bounded to 32 profiles.

Profile storage requires a local filesystem supporting hard links (such as NTFS or a typical Linux filesystem), so creation can install a complete encrypted file without overwriting an existing name. FAT/exFAT and some network mounts are not supported: set SUBSTACK_MCP_HOME to a suitable local directory. Do not use --force to work around an unsupported filesystem.

Set SUBSTACK_PROFILES=work,personal in your MCP client's environment to se