@conorbronsdon/substack-mcp

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

License

MIT