substack-mcp

# 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 ## Installation ```bash # Clone the repo git clone https://github.com/acolle/substack-mcp.git cd substack-mcp # Install dependencies pip install -r requirements.txt ``` ## Testing ```bash python -m unittest discover -s tests ``` ## Setup ### 1. Get your Substack credentials 1. Go to your Substack dashboard in Chrome/Safari 2. Open DevTools (Cmd+Option+I or F12) 3. Go to Application tab → Cookies → your-substack.substack.com 4. Find `substack.sid` and copy its value ### 2. Create credentials file ```bash # Create ~/.substackrc cat > ~/.substackrc << 'EOF' export SUBSTACK_PUBLICATION="your-publication.substack.com" export SUBSTACK_SID="your-cookie-value-here" EOF ``` ### 3. Add to Claude Code ```bash # 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`: ```json { "mcpServers": { "substack": { "command": "bash", "args": ["-c", "source ~/.substackrc && python3 /path/to/substack-mcp/substack_mcp/server.py"] } } } ``` ## Available Tools | Tool | Description | |------|-------------| | `substack_create_draft` | Create a new draft post | | `substack_update_draft` | Update an existing draft | | `substack_append_to_draft` | Append content (for live blogging) | | `substack_add_code_block` | Add a code block to a draft | | `substack_add_image` | Add an image to a draft | | `substack_publish` | Publish a draft | | `substack_post_note` | Post a short note | | `substack_get_drafts` | List all drafts | | `substack_get_posts` | List published posts | | `substack_live_blog_start` | Start a live blogging session | | `substack_live_blog_end` | 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/12345 ``` ### Upload 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. ```python 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: ```json { "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_draft` and `update_draft` automatically add missing `internalRedirect` values for any image nodes. - Image captions are emitted as separate italic paragraphs (not `imageCaption` nodes) to avoid editor rendering issues. - For best rendering results, upload images through `upload_image()` and use the returned metadata. ## Credits - Built on [Jakub Slys's Substack API reverse engineering](https://iam.slys.dev/p/no-official-api-no-problem-how-i) - Uses [Anthropic's MCP Python SDK](https://github.com/anthropics/mcp) ## License MIT ## Disclaimer This uses Substack's unofficial/internal API which may change without notice. Use at your own risk.