Substack MCP Server

A Model Context Protocol server that lets Claude read from — and optionally draft to — a Substack publication.

Substack has no official public API. This server uses the same unofficial JSON endpoints the Substack website itself calls, plus the public RSS feed. That has two consequences worth knowing up front:

• Read tools work with no login and are reliable.
• Writing (drafts) needs your session cookie, and because it rides on undocumented endpoints, treat create_draft as experimental — Substack can change these endpoints without notice.

Tools

Tool	Auth?	What it does
get_publication_info	no	Connection check; publication name, URL, latest post.
list_recent_posts	no	Recent posts, newest first, with free/paid flag.
search_posts	no	Keyword search across your posts.
get_post	no	Full content of one post by slug (API, RSS fallback).
create_draft	yes	Creates a draft (never publishes). Attaches your author byline. Needs SUBSTACK_SID.
list_drafts	yes	Lists your unpublished drafts with edit URLs.
create_note	yes	Publishes a plain-text Note. Live/public — no draft step.
create_note_with_link	yes	Publishes a Note with a link-preview card. Live/public.
create_note_with_image	yes	Publishes a Note with an uploaded image. Live/public.

A local .env file (next to server.py) is loaded automatically, so you can keep SUBSTACK_PUBLICATION / SUBSTACK_SID there for local runs instead of exporting them by hand. Copy .env.example to .env to start.

Setup

cd substack-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Set your publication (subdomain only):

export SUBSTACK_PUBLICATION=your-subdomain
python server.py   # should start and wait silently on stdio

Ctrl-C to stop. If it exits with an error about SUBSTACK_PUBLICATION, that variable isn't set.

Connect it to Claude Code

From the repo directory:

claude mcp add substack \
  --scope user \
  --env SUBSTACK_PUBLICATION=your-subdomain \
  -- /absolute/path/to/substack-mcp/.venv/bin/python /absolute/path/to/substack-mcp/server.py

Then claude mcp get substack should show ✔ Connected. The write tools read SUBSTACK_SID from your local .env (see below), so it never lands in config.

Connect it to Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add (use absolute paths, and your venv's python if you made one):

{
  "mcpServers": {
    "substack": {
      "command": "/absolute/path/to/substack-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/substack-mcp/server.py"],
      "env": {
        "SUBSTACK_PUBLICATION": "your-subdomain",
        "SUBSTACK_SID": ""
      }
    }
  }
}

Fully quit and reopen Claude Desktop. You should see the substack tools appear. Try: "Use the substack tools to list my 5 most recent posts."

Enabling the write tools (optional)

The write tools (create_draft, create_note, create_note_with_link, create_note_with_image, list_drafts) act on your behalf, so they need proof you're logged in. There's no API key, so it uses your browser session cookie:

1. Log into Substack in your browser.
2. Open DevTools → Application (Chrome) / Storage (Firefox) → Cookies → https://substack.com.
3. Copy the value of the substack.sid cookie.
4. Copy .env.example to .env and paste it after SUBSTACK_SID=.

Security notes: this cookie is equivalent to your login — anyone with it can act as you. It lives only in your local .env (git-ignored). Don't commit it, don't paste it into chats, and rotate it (log out / back in) if it leaks. It expires periodically; when a write tool starts returning auth errors, refresh it.

⚠️ Notes publish immediately. create_draft only ever makes a draft you publish yourself, but create_note* post to your public Notes feed the moment they run — there is no draft step. Treat them as a real send.

Limitations & notes

• Draft and note bodies convert plain paragraphs (blank-line separated) into Substack's editor format — no bold/italic/headings yet. Drafts are meant to seed a post you finish in the editor.
• Paywalled post bodies only come through in full when authenticated; otherwise you get the free preview.
• The unofficial endpoints can change without notice. If a read tool starts failing, the /api/v1/archive shape or /feed is the first thing to check.

Extending it

Natural next tools: list_comments(slug), delete_note(id), scheduling, or richer Markdown→ProseMirror conversion (bold/italic/links/headings). Each is a new @mcp.tool() function in server.py.

Support

Every tool here started as a mess in my own week — a client problem I kept solving by hand, until I built something that could run it for me. I ship them open, MIT, because a tool you can hand to someone else is the only proof the thinking was real.

A coffee keeps the tools free and maintained, and funds the next one — built in the open.

Disclaimer

This project is not affiliated with or endorsed by Substack. It uses undocumented endpoints that may change or break at any time. Use at your own risk, and in line with Substack's terms of service.