Substack MCP Server
Allows for the programmatic management of Substack content, including creating, updating, and publishing draft posts, uploading images to Substack's CDN, posting short-form Notes, and managing live blogging sessions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Substack MCP Server
A Model Context Protocol (MCP) server for Substack integration with Claude Code and other MCP-compatible AI tools.
Features
Create and manage drafts - Create, update, and publish Substack posts programmatically
Image upload - Upload images to Substack's CDN with proper metadata
Live blogging - Real-time post updates with timestamps
Notes - Post short-form content to Substack Notes
Full ProseMirror support - Proper document structure for Substack's editor
Related MCP server: Substack MCP Server
Installation
# Clone the repo
git clone https://github.com/acolle/substack-mcp.git
cd substack-mcp
# Install dependencies
pip install -r requirements.txtTesting
python -m unittest discover -s testsSetup
1. Get your Substack credentials
Go to your Substack dashboard in Chrome/Safari
Open DevTools (Cmd+Option+I or F12)
Go to Application tab → Cookies → your-substack.substack.com
Find
substack.sidand copy its value
2. Create credentials file
# Create ~/.substackrc
cat > ~/.substackrc << 'EOF'
export SUBSTACK_PUBLICATION="your-publication.substack.com"
export SUBSTACK_SID="your-cookie-value-here"
EOF3. Add to Claude Code
# Add the MCP server to Claude Code
claude mcp add substack \
--command "bash" \
--args "-c" "source ~/.substackrc && python3 $(pwd)/substack_mcp/server.py"Or manually add to ~/.claude.json:
{
"mcpServers": {
"substack": {
"command": "bash",
"args": ["-c", "source ~/.substackrc && python3 /path/to/substack-mcp/substack_mcp/server.py"]
}
}
}Available Tools
Tool | Description |
| Create a new draft post |
| Update an existing draft |
| Append content (for live blogging) |
| Add a code block to a draft |
| Add an image to a draft |
| Publish a draft |
| Post a short note |
| List all drafts |
| List published posts |
| Start a live blogging session |
| End live blogging session |
Usage Examples
Create a post with Claude Code
You: Create a new Substack post about AI tools
Claude: I'll create a draft for you...
[Uses substack_create_draft tool]
Created draft 12345. Edit at: https://your-pub.substack.com/publish/post/12345Upload and embed images
You: Add this diagram to my post [image path]
Claude: I'll upload the image and add it to your draft...
[Uses substack_add_image tool]
Image added successfully.Live blogging
You: Start a live blog for the product launch
Claude: Starting live blog session...
[Uses substack_live_blog_start tool]
Live blog started. I'll append updates as they happen.API Reference
SubstackClient
The core client for interacting with Substack's API.
from substack_client import SubstackClient, SubstackDocument
# rate_limit is seconds between requests; timeout is per-request timeout.
client = SubstackClient(token="your-sid", publication="your-pub.substack.com", rate_limit=0.5, timeout=30.0)
# Upload an image
img = client.upload_image("/path/to/image.png")
# Returns: {"url": "https://...", "width": 800, "height": 600, "bytes": 12345, "contentType": "image/png"}
# Create a document
doc = SubstackDocument()
doc.heading("My Post", level=2)
doc.paragraph("Hello world!")
doc.image(src=img['url'], width=img['width'], height=img['height'],
bytes_size=img['bytes'], content_type=img['contentType'])
# Create and publish
draft = client.create_draft(title="My Post", body=doc)
client.publish_draft(draft.id, send_email=False)Key Technical Details
Image Node Structure
Substack uses ProseMirror and requires specific attributes for images:
{
"type": "captionedImage",
"content": [{
"type": "image2",
"attrs": {
"src": "https://substack-post-media.s3.amazonaws.com/...",
"width": 800,
"height": 600,
"bytes": 12345,
"type": "image/png",
"internalRedirect": "https://pub.substack.com/i/{draft_id}?img={encoded_url}",
"belowTheFold": false,
"topImage": false,
"isProcessing": false
}
}]
}The internalRedirect field is required - without it, Substack's editor fails to render the document.
Image Handling Notes
create_draftandupdate_draftautomatically add missinginternalRedirectvalues for any image nodes.Image captions are emitted as separate italic paragraphs (not
imageCaptionnodes) to avoid editor rendering issues.For best rendering results, upload images through
upload_image()and use the returned metadata.
Credits
License
MIT
Disclaimer
This uses Substack's unofficial/internal API which may change without notice. Use at your own risk.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Substack MCP server for ChatGPT, Claude and any AI agent: create post, schedule post, publish Note, reply to Notes, send direct message, moderate comments, list subscribers and get post stats in your own Substack account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Substack yourself; Cotlet does not store your password and you need no Substack API key. About the official Substack API: Substack has only a limited API (checked 11 Oct 2026). Its Developer API looks up public creator profiles after approval, and there is no public API to write posts or Notes, manage subscribers or send email. Setup and FAQ: https://cotlet.dev/integrations/substack-api-mcp-server
Blog MCP server for AI agents. One signup call returns a blog, an API key and a live URL; then your agent publishes markdown posts and gets public URLs back. Your agent does the writing; you get a dashboard for stats.
A blog CMS that AI agents write into over MCP: Markdown drafts, versions, media, human approval.
Manage WordPress blogs and WooCommerce shops from Claude, ChatGPT, Cursor and other MCP apps.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceEnables interaction with Substack publications through natural conversation, allowing users to create posts with cover images, publish notes, manage content, and retrieve profile information.82 npm-
- AlicenseAqualityDmaintenanceEnables AI tools to programmatically manage Substack content, including creating drafts, publishing posts, and posting to Substack Notes. It supports image uploads, live blogging, and document formatting compatible with Substack's ProseMirror editor.119MIT
- AlicenseNot gradedqualityDmaintenanceCreate, manage, and publish Substack posts with full rich text formatting directly from Claude Desktop or any MCP-compatible client.71 npm26MIT
- AlicenseNot gradedqualityDmaintenanceEnables managing Substack publications: publish Notes and posts, manage drafts, pull analytics, and read any publication's public feed via MCP.MIT