substack-mcp

An MCP server for Substack that lets AI assistants read your publication data and manage drafts.

Safe by design: This server can create and edit drafts but cannot publish or delete posts. You always review and publish manually through Substack's editor.

Tools

Read

Tool	Description
`get_subscriber_count`	Get your publication's current subscriber count
`list_published_posts`	List published posts with pagination
`list_drafts`	List draft posts
`get_post`	Get full content of a published post by ID
`get_draft`	Get full content of a draft by ID
`get_post_comments`	Get comments on a published post

Write

Tool	Description
`create_draft`	Create a new draft from markdown
`update_draft`	Update an existing draft (unpublished only)
`upload_image`	Upload an image to Substack's CDN
`create_note`	Publish a Substack Note (short-form, publishes immediately)
`create_note_with_link`	Publish a Note with a link card attachment

Intentionally excluded

Publish posts — Publishing long-form posts should be a deliberate human action
Delete — Too destructive for an AI tool
Schedule — Use Substack's editor for scheduling

Setup

1. Get your credentials

Open your Substack in a browser, then:

Session token: Navigate to your publication, open DevTools → Application → Cookies → copy the value of connect.sid (URL-encoded string starting with s%3A)
User ID: In DevTools Console, run: fetch('/api/v1/archive?sort=new&limit=1').then(r=>r.json()).then(d=>console.log(d[0]?.publishedBylines?.[0]?.id))
Publication URL: Your Substack URL, including custom domain if you have one (e.g., https://newsletter.yourdomain.com or https://yourblog.substack.com)

2. Configure your MCP client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "substack": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/substack-mcp"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "https://yourblog.substack.com",
        "SUBSTACK_SESSION_TOKEN": "your-session-token",
        "SUBSTACK_USER_ID": "your-user-id"
      }
    }
  }
}

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "substack": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/substack-mcp"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "https://yourblog.substack.com",
        "SUBSTACK_SESSION_TOKEN": "your-session-token",
        "SUBSTACK_USER_ID": "your-user-id"
      }
    }
  }
}

3. Verify

Ask your AI assistant: "How many Substack subscribers do I have?"

Token expiration

Substack session tokens expire periodically (typically ~90 days). If you get authentication errors, grab a fresh connect.sid cookie from your browser and update the env var. Make sure ad blockers are disabled when copying the cookie.

Markdown support

The create_draft and update_draft tools accept markdown and convert it to Substack's native format. Supported:

Paragraphs, headings (h1–h6)
Bold, italic, inline code
Links
Images
Bullet and numbered lists
Code blocks (with language)
Blockquotes
Horizontal rules

Important notes

This server uses Substack's unofficial API. It may break if Substack changes their endpoints.
Session tokens are sent as cookies. Keep your SUBSTACK_SESSION_TOKEN secure.
The server validates authentication on startup and will fail fast if your token is expired.

Development

git clone https://github.com/conorbronsdon/substack-mcp.git
cd substack-mcp
npm install
npm run build

Run locally:

SUBSTACK_PUBLICATION_URL=https://yourblog.substack.com \
SUBSTACK_SESSION_TOKEN=your-token \
SUBSTACK_USER_ID=your-id \
npm start

Disclaimer

All views, opinions, and statements expressed on this account are solely my own and are made in my personal capacity. They do not reflect, and should not be construed as reflecting, the views, positions, or policies of Modular. This account is not affiliated with, authorized by, or endorsed by Modular in any way.

License

MIT