conorbronsdon/substack-mcp
read posts, manage drafts, publish Notes, get comments, and upload images. Safe by design: cannot publish or delete posts.
Ask AI about conorbronsdon/substack-mcp
Powered by Claude Β· Grounded in docs
I know everything about conorbronsdon/substack-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 withs%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.comorhttps://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_TOKENsecure. - 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
