# substack-mcp

A Model Context Protocol (MCP) server for Substack. Lets Claude Code create
drafts, upload images, set cover thumbnails, schedule, and publish posts on
your Substack publication.

> Built on top of [`python-substack`](https://github.com/ma2za/python-substack).
> Uses Substack's internal API (no public posting API exists). Not affiliated
> with Substack Inc.

## Tools

**Required**

- `create_draft(title, content_markdown, subtitle?, audience?)` — Create a new draft from Markdown.
- `update_draft(post_id, title?, subtitle?, content_markdown?, audience?)` — Edit an existing draft.
- `upload_image(image_path)` — Upload a local file or remote URL to Substack's CDN, returning the URL.
- `publish_draft(post_id, send_email?, share_automatically?)` — Publish immediately. `send_email` toggles email delivery.

**Recommended**

- `schedule_draft(post_id, iso_datetime)` — Schedule a publish for a future date/time (ISO 8601).
- `unschedule_draft(post_id)` — Cancel a scheduled publish.
- `set_cover_image(post_id, image_url)` — Set the cover thumbnail (from `upload_image` URL).

**Utility**

- `list_drafts(limit?)` — List recent drafts.
- `get_draft(post_id)` — Get a draft's full body.
- `delete_draft(post_id)` — Permanent deletion.

## Setup

```bash
# 1. Install dependencies
uv pip install -e .

# 2. Make sure you're logged in to Substack in Chrome (or Brave/Edge) — that's it.

# 3. Save credentials — auto-detects your existing browser session
substack-mcp-setup

# 4. Register with Claude Code
claude mcp add substack-mcp --scope user -- /Users/$USER/substack/.venv/bin/substack-mcp
```

Restart Claude Code, then `/mcp` should show `substack-mcp` as `connected`.

### Run fully in the cloud with Cloudflare

The Cloudflare deployment exposes a stable, OAuth 2.1-protected Streamable HTTP
endpoint at `https://<worker>.workers.dev/mcp`. ChatGPT performs the writing and
reasoning; the Worker and its on-demand Python Container only execute Substack
operations. No OpenAI API key, Secure MCP Tunnel, or always-on computer is
required.

Requirements:

- a Cloudflare account with Workers Containers enabled
- Node.js 22.18 or newer
- a GitHub OAuth App used only to verify who may connect
- a current `substack.sid` session token (store it as a Cloudflare secret)

Install and create the OAuth state store:

```bash
npm install
npx wrangler login
npx wrangler kv namespace create OAUTH_KV
```

Put the returned namespace ID in `wrangler.jsonc` in place of
`REPLACE_WITH_OAUTH_KV_ID`. Your final Worker URL will normally be:

```text
https://substack-mcp.<your-workers-subdomain>.workers.dev
```

Create a GitHub OAuth App with that URL as its homepage and
`https://substack-mcp.<your-workers-subdomain>.workers.dev/callback` as its
authorization callback URL. Then store all private values using Wrangler's
interactive secret prompt (never commit them or paste them into chat):

```bash
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put ALLOWED_GITHUB_LOGINS
npx wrangler secret put SUBSTACK_PUBLICATION_URL
npx wrangler secret put SUBSTACK_SESSION_TOKEN
npm run deploy
```

`ALLOWED_GITHUB_LOGINS` is a comma-separated allowlist, for example
`nanameru`. `SUBSTACK_PUBLICATION_URL` is the full publication URL. For the
session token, copy only the value of the `substack.sid` cookie from a browser
that is logged in to Substack. The browser is needed once for setup; it does not
need to remain open afterward. Signing out of all Substack sessions invalidates
this credential, so update the Cloudflare secret after doing that.

In ChatGPT developer mode, create an app/connector from:

```text
https://substack-mcp.<your-workers-subdomain>.workers.dev/mcp
```

Choose OAuth when prompted and sign in with an allowlisted GitHub account.
Draft creation is non-public. Publishing, subscriber email, draft deletion, and
Notes remain confirmation-gated by the tool descriptions and the bundled
`substack-article` skill.

### Connect to ChatGPT Work with Secure MCP Tunnel

This server uses the local `substack.sid` browser session and should not be
published directly on the internet. For a private ChatGPT Work connection, use
[OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels).
The tunnel keeps the stdio MCP and Substack credential on your Mac while making
the tools available to an authorized ChatGPT workspace.

Prerequisites:

- macOS with Chrome, Brave, Edge, Chromium, Vivaldi, or Opera already signed in
  to Substack
- ChatGPT developer mode enabled
- an OpenAI Platform tunnel ID associated with the target ChatGPT workspace
- `tunnel-client` installed from OpenAI Platform tunnel settings
- a tunnel runtime API key with **Tunnels Read + Use** permission

Run:

```bash
git clone https://github.com/nanameru/substack-mcp.git
cd substack-mcp

# Keep these values out of shell history when possible. Never commit them.
export SUBSTACK_TUNNEL_ID="tunnel_..."
export CONTROL_PLANE_API_KEY="sk-..."

./scripts/setup-chatgpt-work-tunnel.sh
tunnel-client run --profile substack-mcp
```

Then open ChatGPT Plugins, create a developer-mode app, choose **Tunnel** under
Connection, and select the tunnel. The Mac and `tunnel-client` process must stay
running while ChatGPT calls the Substack tools.

The helper never prints or uploads the Substack session token. It runs
`substack-mcp-setup` locally, stores the credential with `0600` permissions, and
points the tunnel at the local stdio command.

### (Optional) Install the `substack-article` skill

This repo also ships a [Vercel Skills](https://skills.sh/)-compatible **agent skill**
that uses the MCP above to plan, draft, generate a thumbnail, and publish a
Substack article in one flow.

```bash
# Globally for all projects
npx skills add nanameru/substack-mcp -g -a claude-code -y

# Or scoped to the current project
npx skills add nanameru/substack-mcp -a claude-code
```

Restart Claude Code. The skill is automatically invoked when you say things like
「Substack 記事を書いて」 / 「Substack に投稿して」 / 「短文ポストして」.

`npx skills` works with Claude Code, Cursor, Codex, OpenCode, GitHub Copilot,
and 50+ other agents. See [skills.sh](https://skills.sh/) for details.

The skill expects:

- `substack-mcp` registered as an MCP (above)
- `codex` MCP registered (for thumbnail generation; optional if you skip thumbnails)
- macOS with Hiragino fonts installed (default on macOS for Japanese text overlay)

See `skills/substack-article/SKILL.md` for the full flow and guardrails.

### How auth works

By default `substack-mcp-setup` reads the `substack.sid` cookie directly from
your existing Chrome session via [pycookiecheat](https://pypi.org/project/pycookiecheat/).
Substack can't tell anything was automated because **nothing was**: it's the
same session you're already using.

macOS will prompt once for Keychain access ("Chrome Safe Storage"). Click
"Always Allow" so it doesn't ask again next time.

Supports: Chrome, Brave, Edge, Chromium, Vivaldi, Opera.

### Fallback modes

```bash
# Specific browser
substack-mcp-setup --from-browser brave

# Playwright-based (often blocked by Substack — use --chrome instead)
substack-mcp-setup --browser

# Manual paste from DevTools
substack-mcp-setup --manual
```

Tokens are stored at `~/Library/Application Support/substack-mcp/config.json`
with `0600` permissions.

## Security

The `substack.sid` cookie is **equivalent to a password** — anyone with it has
full account access (publish posts, edit billing, etc.). Treat it as such.

### Where the token lives

- macOS: `~/Library/Application Support/substack-mcp/config.json` (mode `0600`)
- Linux: `~/.config/substack-mcp/config.json` (mode `0600`)
- Or via env vars: `SUBSTACK_PUBLICATION_URL` + `SUBSTACK_SESSION_TOKEN` (env
  vars are inherited by child processes — be aware when spawning subprocesses)

The `.gitignore` excludes `config.json`; never commit it. The MCP also writes
a temporary cookie file via `tempfile.mkstemp` (mode `0600`) and deletes it in
a `finally` block — see `auth.py:write_cookie_file`.

### If a token leaks

1. **Sign out of all sessions**: Substack → Settings → Security → "Sign out of
   all sessions". This invalidates every existing `substack.sid` immediately.
2. Log back in to Substack in your browser.
3. Re-run `substack-mcp-setup` to capture the new cookie.

### Image upload safety

`upload_image` only accepts:
- HTTP(S) URLs, or
- Local files with image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`,
  `.heic`, `.heif`) that are **not** under sensitive system paths
  (`/etc`, `/System`, `~/.ssh`, `~/.aws`, `~/Library/Keychains`, etc.)

This guards against an assistant being tricked (via prompt injection in
fetched content) into uploading e.g. an SSH private key to Substack's CDN.

**Known limitation**: Markdown image syntax `![alt](path)` inside `create_draft`
is processed by `python-substack` and bypasses this validation. If you pass
untrusted Markdown, sanitize image paths first.

### Dependencies

Versions are pinned with `~=` (compatible release, no major bumps). Bumping
`python-substack` in particular should be reviewed — it talks to Substack's
private API and lives outside Substack's official surface.

## Notes

- `audience` accepts: `everyone` (default), `only_paid`, `founding`, `only_free`.
- Markdown image syntax `![alt](path/or/url)` auto-uploads local files when you call `create_draft`.
- The cover image (set via `set_cover_image`) is what appears on your publication
  homepage and in social shares. If you don't set one explicitly, Substack
  typically uses the first image in the body.