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:

1. Session token: Navigate to your publication, open DevTools → Application → Cookies → copy the value of connect.sid (URL-encoded string starting with s%3A)
2. 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))
3. 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