# Substack MCP server

> Lets an AI client create and edit Substack drafts, publish posts, query subscribers, and upload images through a live session.

- Repository: https://github.com/marcomoauro/substack-mcp
- Page: https://hostedmcp.org/servers/marcomoauro/substack-mcp
- Transport: stdio
- Stars: 94
- License: MIT
- Latest version: 1.3.2

## Install

### Claude Code

```sh
claude mcp add --env 'SUBSTACK_SESSION_TOKEN=<YOUR_SUBSTACK_SESSION_TOKEN>' --env 'SUBSTACK_PUBLICATION_URL=<SUBSTACK_PUBLICATION_URL>' --env 'SUBSTACK_USER_ID=<SUBSTACK_USER_ID>' substack-mcp -- npx -y substack-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "substack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "substack-mcp"
      ],
      "env": {
        "SUBSTACK_SESSION_TOKEN": "<YOUR_SUBSTACK_SESSION_TOKEN>",
        "SUBSTACK_PUBLICATION_URL": "<SUBSTACK_PUBLICATION_URL>",
        "SUBSTACK_USER_ID": "<SUBSTACK_USER_ID>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "substack-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "substack-mcp"
      ],
      "env": {
        "SUBSTACK_SESSION_TOKEN": "<YOUR_SUBSTACK_SESSION_TOKEN>",
        "SUBSTACK_PUBLICATION_URL": "<SUBSTACK_PUBLICATION_URL>",
        "SUBSTACK_USER_ID": "<SUBSTACK_USER_ID>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"substack-mcp","type":"stdio","command":"npx","args":["-y","substack-mcp"],"env":{"SUBSTACK_SESSION_TOKEN":"<YOUR_SUBSTACK_SESSION_TOKEN>","SUBSTACK_PUBLICATION_URL":"<SUBSTACK_PUBLICATION_URL>","SUBSTACK_USER_ID":"<SUBSTACK_USER_ID>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "substack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "substack-mcp"
      ],
      "env": {
        "SUBSTACK_SESSION_TOKEN": "<YOUR_SUBSTACK_SESSION_TOKEN>",
        "SUBSTACK_PUBLICATION_URL": "<SUBSTACK_PUBLICATION_URL>",
        "SUBSTACK_USER_ID": "<SUBSTACK_USER_ID>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add substack-mcp --env 'SUBSTACK_SESSION_TOKEN=<YOUR_SUBSTACK_SESSION_TOKEN>' --env 'SUBSTACK_SESSION_TOKEN=<YOUR_SUBSTACK_SESSION_TOKEN>' --env 'SUBSTACK_PUBLICATION_URL=<SUBSTACK_PUBLICATION_URL>' --env 'SUBSTACK_PUBLICATION_URL=<SUBSTACK_PUBLICATION_URL>' --env 'SUBSTACK_USER_ID=<SUBSTACK_USER_ID>' --env 'SUBSTACK_USER_ID=<SUBSTACK_USER_ID>' -- npx -y substack-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.substack-mcp]
command = "npx"
args = ["-y", "substack-mcp"]

[mcp_servers.substack-mcp.env]
SUBSTACK_SESSION_TOKEN = "<YOUR_SUBSTACK_SESSION_TOKEN>"
SUBSTACK_PUBLICATION_URL = "<SUBSTACK_PUBLICATION_URL>"
SUBSTACK_USER_ID = "<SUBSTACK_USER_ID>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'SUBSTACK_SESSION_TOKEN=<YOUR_SUBSTACK_SESSION_TOKEN>' -e 'SUBSTACK_SESSION_TOKEN=<YOUR_SUBSTACK_SESSION_TOKEN>' -e 'SUBSTACK_PUBLICATION_URL=<SUBSTACK_PUBLICATION_URL>' -e 'SUBSTACK_PUBLICATION_URL=<SUBSTACK_PUBLICATION_URL>' -e 'SUBSTACK_USER_ID=<SUBSTACK_USER_ID>' -e 'SUBSTACK_USER_ID=<SUBSTACK_USER_ID>' substack-mcp npx -- -y substack-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "substack-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "substack-mcp"
      ],
      "env": {
        "SUBSTACK_SESSION_TOKEN": "<YOUR_SUBSTACK_SESSION_TOKEN>",
        "SUBSTACK_PUBLICATION_URL": "<SUBSTACK_PUBLICATION_URL>",
        "SUBSTACK_USER_ID": "<SUBSTACK_USER_ID>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `SUBSTACK_SESSION_TOKEN` | yes | yes | Value of the substack.sid or connect.sid cookie from your authenticated Substack session |
| `SUBSTACK_SESSION_TOKEN` | yes | yes | Value of the substack.sid or connect.sid cookie from your authenticated Substack session |
| `SUBSTACK_PUBLICATION_URL` | yes | no | Full URL of your Substack publication, including https:// |
| `SUBSTACK_PUBLICATION_URL` | yes | no | Full URL of your Substack publication, including https:// |
| `SUBSTACK_USER_ID` | yes | no | Numeric user ID returned by Substack's publication_user request |
| `SUBSTACK_USER_ID` | yes | no | Numeric user ID returned by Substack's publication_user request |
| `SUBSTACK_PUBLICATION_URL` | no | no |  |
| `SUBSTACK_SESSION_TOKEN` | no | no |  |
| `SUBSTACK_USER_ID` | no | no |  |

## Tools (55)

- `title`
- `subtitle`
- `body`
- `filters`
- `search`
- `sort_by`
- `sort_direction`
- `limit`
- `offset`
- `columns`
- `max_wait_seconds`
- `status`
- `draft_id`
- `url`
- `path`
- `post_id`
- `draft_title`
- `draft_subtitle`
- `audience`
- `write_comment_permissions`
- `default_comment_sort`
- `cover_image`
- `social_title`
- `description`
- `search_engine_title`
- `search_engine_description`
- `slug`
- `send`
- `full`
- `include_hidden`
- `tag_name`
- `create_if_missing`
- `active_only`
- `after`
- `include_body`
- `tab`
- `cursor`
- `include_tabs`
- `user_id`
- `type`
- `comment_id`
- `include_replies`
- `tab_id`
- `order_by`
- `order_direction`
- `report`
- `retention`
- `retention_summary`
- `growth_sources`
- `growth_events`
- `audience_overlap`
- `audience_locations`
- `subscriber_notes`
- `paid_subscriber_growth`
- `network_attribution`

## FAQ

### How do I authenticate the Substack MCP server?

You sign in to Substack and provide your publication URL, session token and user ID via environment variables; the server uses your authenticated web session.

### Can the Substack MCP server create and update posts?

Yes, it can create drafts, replace a draft's body with a structured document, and manage posts across drafts, published and scheduled lists.

### Can I filter and export my Substack subscribers?

Yes, you can filter subscribers by many columns and operators, and export the full matching set with engagement metrics.

### Can I upload images to Substack with this server?

Yes, upload_image re-hosts an image from a URL or local file on Substack and returns a URL usable in post bodies or cover images.

### How many tools does the server expose?

The server exposes 27 tools covering posts, subscribers, analytics, feeds, tags, comments and images.