Substack by Cotlet MCP server

Substack API and MCP server, self-hosted

A Substack API and a Substack MCP server you run on your own computer, in Python, on the session of your own Google Chrome. All 50 Substack tools we run in production at Cotlet: posts and drafts from Markdown, publishing and scheduling, Notes, comments, subscribers, stats, recommendations and direct messages.

Substack has no public API to write posts, publish Notes or manage subscribers, and no official MCP server. This repo gives you both:

• MCP server for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. Setup
• REST API on http://127.0.0.1:8787/api/v1/substack, with OpenAPI docs at /docs. Setup
• Python: call("list_posts", status="draft"), plus 14 ready scripts in examples/.

It is for technical people who want to run it themselves, for noncommercial use only (license). If you want it running 24/7 on a server, kept working when Substack changes its site, for a team or a business, use the hosted version at cotlet.dev.

git clone https://github.com/cotletdev/substack-api-mcp-server.git && cd substack-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
substack-mcp connect                               # reads your Substack session from Chrome
substack-mcp call list_posts
claude mcp add substack -- "$PWD/.venv/bin/substack-mcp" mcp

Contents

• How it works
• Requirements
• Install
• Connect your Chrome
• MCP server
• REST API
• Python and the example scripts
• All 50 tools
• Configuration
• Security and your Substack account
• Errors
• Self-hosted or hosted

How it works

AI agent (MCP) / script (REST, Python) ──▶ substack-mcp on your computer ──your Substack cookies──▶ substack.com
                                                     ▲
                         substack-mcp connect ───────┘ reads them once from your Chrome (DevTools Protocol)

1. You sign in to Substack in your own Chrome, the way you always do.
2. substack-mcp connect attaches to that Chrome through the Chrome DevTools Protocol, reads the substack.com cookies and saves them to ~/.config/substack-api-mcp/session.json, readable by your user only. Substack signs in by an emailed code or link, so there is no password to see or store.
3. Every tool call is a request to Substack's own web app endpoints (substack.com/api/v1 for the reader side, yourname.substack.com/api/v1 for your publication's dashboard) with those cookies, sent with curl_cffi, which copies Chrome's TLS fingerprint. No headless browser runs.

Substack's session cookie (substack.sid) lasts about three months. When Substack signs you out, the server reads the cookies from Chrome again, if Chrome is open with remote debugging on.

Requirements

Shortened. The full README is on GitHub.