# Substack API MCP

<p align="center">
  <img src="assets/claude-substack.jpg" alt="Claude + Substack" width="720" />
</p>

Substack does **not** provide a native public API for publishing posts.

But authors who want to draft, publish, and schedule from AI agents (Cursor, Claude, and other MCP hosts) still need a way out. **This is the MCP server to publish to Substack via any agent.**

**Will not start without a valid `APISUBSTACK_API_KEY` (`ask_*`). Get API key here: [apisubstack.com](https://apisubstack.com/).**

## Why this exists

| Reality | What we built |
|---|---|
| No official Substack write/publish API for authors | A posting MCP so agents can create drafts, publish now, and schedule |
| Authors live in the browser editor | Authors publish through their agents instead |
| Session-cookie auth is the practical path today | `substack.sid` + your publication URL, gated by an API Substack key |

## Examples

- [ignalex.substack.com](https://ignalex.substack.com/)

## Tools

| Tool | Description |
|---|---|
| `test_connection` | Verify `substack.sid` and return profile |
| `create_post` | Create draft / publish now / schedule (+ optional tags) |
| `get_draft` | Fetch draft by id |
| `pangram_detection` | Pangram AI-text / AI-slop check on a draft |
| `update_draft` | Update draft fields |
| `publish_post` | Publish existing draft |
| `schedule_post` | Schedule existing draft |
| `delete_draft` | Delete draft |
| `list_tags` | List publication tags |
| `create_tag` | Create tag |
| `set_tags` | Ensure + attach tags |
| `get_post_tags` | List tags on a post/draft |
| `create_note` | Create a Substack Note (optional link attachment) |
| `delete_note` | Delete a Substack Note by id |

## Install

```bash
cd /path/to/Substack-API-MCP
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Auth env

1. Sign in at [apisubstack.com](https://apisubstack.com/), start the free trial, generate an `ask_*` API key.
2. Copy your Substack `substack.sid` cookie:
   - Open Chrome and sign in to Substack.
   - Open DevTools → **Application** → **Cookies**.
   - Select `https://substack.com` (or your publication host, e.g. `https://yourname.substack.com`).
   - Find the cookie named `substack.sid` and copy its **Value**.
3. Export:

```bash
export APISUBSTACK_API_KEY="ask_YOUR_KEY"
export SUBSTACK_PUBLICATION_URL="https://yourname.substack.com"
export SUBSTACK_SID="YOUR_SUBSTACK_SID_VALUE"
# optional
# export SUBSTACK_USER_ID="123456"
```

Cookies expire. If you get `401/403`, refresh `substack.sid` and try again.

## Run

```bash
substack-api-mcp
# or
python -m substack_api_mcp
```

## Cursor / Claude Desktop config

See `mcp.example.json`:

```json
{
  "mcpServers": {
    "substack-api": {
      "command": "/ABSOLUTE/PATH/TO/Substack-API-MCP/.venv/bin/substack-api-mcp",
      "args": [],
      "env": {
        "APISUBSTACK_API_KEY": "ask_YOUR_KEY",
        "SUBSTACK_PUBLICATION_URL": "https://yourname.substack.com",
        "SUBSTACK_SID": "YOUR_SUBSTACK_SID_VALUE"
      }
    }
  }
}
```

Use absolute paths. Restart the host after config changes.

## License

**Attribution-or-Royalty** (source available). See [`LICENSE`](LICENSE) and [`COMMERCIAL_LICENSE.md`](COMMERCIAL_LICENSE.md).

- Non-commercial use: allowed (keep copyright + license notice).
- Commercial use: either **visible attribution** everywhere the software is used, **or** a paid **royalty / commercial license** via [apisubstack.com](https://apisubstack.com/).

Use at your own risk. Not affiliated with Substack. Built so authors can publish through their agents when Substack itself does not offer a native publishing API.