Substack by Cotlet — Claude Code MCP server: posts, notes, subscribers
A self-hosted MCP server and REST API for Substack: publish posts from Markdown, handle notes, comments, subscribers and stats. Useful if you run a publication and want to drive it from an agent.
claude mcp add --transport http substack https://cotlet.dev/mcp/v1/substack/connectWhat Substack by Cotlet does
The server runs on your own machine in Python and talks to Substack through your existing Chrome session. Substack has no public API for this, so requests hit the site's internal endpoints with your cookies attached. It ships 50 tools: posts and drafts from Markdown, scheduling, notes, comments, subscribers, stats, recommendations and direct messages.
Setup starts in the browser. You turn on remote debugging in Chrome, sign in to Substack as usual, then run substack-mcp connect. That command attaches over the DevTools Protocol, pulls the substack.com cookies and writes them to ~/.config/substack-api-mcp/session.json, readable only by your user. No password is stored, because Substack signs in with an emailed code or link. Calls go to substack.com/api/v1 through curl_cffi, which mimics Chrome's TLS fingerprint. Nothing runs headless.
You need Python 3.11 or newer and Chrome 144 or newer with a live Substack login. Publishing tools work on the first publication where your account is admin, owner, editor or contributor; reader tools work anywhere. The license is noncommercial, so a team or a business should look elsewhere. The substack.sid cookie lasts about three months. Once Substack signs you out, the server re-reads cookies from Chrome — but only if the browser is open with debugging enabled.
What it helps with
- publish a Markdown file as a post without pasting into the web editor
- schedule a post for later
- pull stats for a published post
- go through the subscriber list
- send a direct message to a reader
Example prompts for the agent
- Publish
draft.mdto my Substack publication - List drafts that have been sitting for a week
- Get stats for my latest posts
How to install Substack by Cotlet
1Platform CLI: remote server
claude mcp add --transport http substack https://cotlet.dev/mcp/v1/substack/connect2Platform CLI
claude mcp add substack-by-cotlet -- uvx substack-api-mcpuvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>
1Platform CLI: remote server
codex mcp add substack-by-cotlet --url https://cotlet.dev/mcp/v1/substack/connect2Platform CLI
codex mcp add substack-by-cotlet -- uvx substack-api-mcpuvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>
Config file
{
"mcpServers": {
"substack-by-cotlet": {
"url": "https://cotlet.dev/mcp/v1/substack/connect"
}
}
}{
"mcpServers": {
"substack-by-cotlet": {
"command": "uvx",
"args": [
"substack-api-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>
Config file
{
"servers": {
"substack-by-cotlet": {
"type": "http",
"url": "https://cotlet.dev/mcp/v1/substack/connect"
}
}
}{
"servers": {
"substack-by-cotlet": {
"type": "stdio",
"command": "uvx",
"args": [
"substack-api-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>
1Platform CLI: remote server
gemini mcp add -t http substack-by-cotlet https://cotlet.dev/mcp/v1/substack/connect2Platform CLI
gemini mcp add substack-by-cotlet uvx substack-api-mcpuvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Substack by Cotlet
How do I install Substack by Cotlet in Claude Code?
For the local server: claude mcp add substack-by-cotlet -- uvx substack-api-mcp. To use Cotlet's hosted endpoint instead: claude mcp add --transport http substack https://cotlet.dev/mcp/v1/substack/connect.
What does Substack by Cotlet do?
It gives an agent access to your Substack publication: posts and drafts, notes, comments, subscribers, stats, recommendations and direct messages. That is 50 tools, plus a REST API at http://127.0.0.1:8787/api/v1/substack and Python calls.
What do I need before running it?
Python 3.11 or newer, Chrome 144 or newer signed in to Substack, and one run of substack-mcp connect. Publishing tools require an admin, owner, editor or contributor role on the publication.
