# Substack by Cotlet

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 3
- Author: cotletdev
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cotletdev/substack-api-mcp-server
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/substack-by-cotlet

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://cotlet.dev/mcp/v1/substack/connect`

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http substack https://cotlet.dev/mcp/v1/substack/connect
```

2. **Platform CLI**
```bash
claude mcp add substack-by-cotlet -- uvx substack-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add substack-by-cotlet --url https://cotlet.dev/mcp/v1/substack/connect
```

2. **Platform CLI**
```bash
codex mcp add substack-by-cotlet -- uvx substack-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "substack-by-cotlet": {
            "url": "https://cotlet.dev/mcp/v1/substack/connect"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "substack-by-cotlet": {
            "type": "http",
            "url": "https://cotlet.dev/mcp/v1/substack/connect"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http substack-by-cotlet https://cotlet.dev/mcp/v1/substack/connect
```

2. **Platform CLI**
```bash
gemini mcp add substack-by-cotlet uvx substack-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from substack-api-mcp <command>

## When to use it
- 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
- Publish `draft.md` to my Substack publication
- List drafts that have been sitting for a week
- Get stats for my latest posts

## Similar
- [Substack MCP Server](https://affpapa.org/en/nevibecode/mcp/conorbronsdon-substack-mcp-server.md) — MCP server · ★ 44
- [substack-ghostwriting](https://affpapa.org/en/nevibecode/skills/substack-ghostwriting.md) — skill · 4400 installs
- [publish-substack-article](https://affpapa.org/en/nevibecode/skills/publish-substack-article.md) — skill · 604 installs
- [newsletter](https://affpapa.org/en/nevibecode/skills/newsletter.md) — skill · 480 installs
- [Booksy by Cotlet](https://affpapa.org/en/nevibecode/mcp/booksy-by-cotlet.md) — MCP server · ★ 2
- [tinysend](https://affpapa.org/en/nevibecode/mcp/tinysend.md) — MCP server

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md