<div align="center">

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.

</div>

---

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.

<a href="https://glama.ai/mcp/servers/conorbronsdon/substack-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/conorbronsdon/substack-mcp/badge" alt="substack-mcp MCP server" /> </a>

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:

   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.

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:

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 <publication>/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 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 select up to 32 distinct profiles. Remove all publication credential variables first: combining profile selection with legacy or named credential variables is an error, including empty variables. Missing, corrupt or invalid selected profiles stop startup; they never fall back to another account. Profiles on disk are never activated by discovery. With multiple profiles, tools require an explicit publication key and CLI reads require --publication.

To roll back, unset SUBSTACK_PROFILES and restore your previous environment configuration. Migration preserves the legacy session byte-for-byte. These files use the existing encryption format. profiles list lists file profiles; select keychain profiles explicitly with SUBSTACK_PROFILES after migration or login. Run substack-mcp status --json for offline configuration diagnostics or substack-mcp doctor --check-auth --json for a bounded read per selected account.

Option B — Get your credentials manually

Open your Substack in a browser, then:

1. Session token: For custom domains, open DevTools → Application → Cookies → https://your-custom-domain and copy connect.sid from the publication's own domain (URL-encoded string starting with s%3A). Do not copy substack.sid from substack.com: it is a different session that the custom domain's admin API rejects with 403. For *.substack.com publications, use connect.sid on that host or substack.sid on .substack.com. The token must match the host of SUBSTACK_PUBLICATION_URL, with the .substack.com fallback only for Substack-hosted publications.
2. User ID: Follow Find your account user ID. Do not use a publication post's byline ID: publications can have multiple authors. This server does not independently verify the supplied ID.
3. Publication URL: Your Substack URL, including custom domain if you have one (e.g., https://newsletter.yourdomain.com or https://yourblog.substack.com)

Find your account user ID

1. In Substack, op