{
"markdown": "\n\n# substack-mcp\n\nSafe creator operations for Substack, via MCP. Prepare rich drafts, publish Notes, inspect analytics, and manage explicitly consented free subscribers across publications. Review and publish long-form posts in Substack.\n\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://www.npmjs.com/package/@conorbronsdon/substack-mcp)\n[](https://modelcontextprotocol.io/)\n[](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=substack-mcp)\n[](https://x.com/ConorBronsdon)\n\n
\n\n---\n\n\n\nThe demo runs actual MCP handlers against offline sample data. No live API calls or publication occur. Follow the [draft workflow](docs/workflow.md) to create, find, export and review a post.\n\nThis server imposes no Bestseller-status check. Use an authenticated account with permission to manage the publication; individual operations depend on your Substack access. Connect through local stdio or self-hosted HTTP.\n\n**Safe by design — with one loud exception:** This server cannot publish or delete long-form posts. Post tools create and edit drafts only; you review and publish manually through Substack's editor. The exception is Substack **Notes**: `create_note` and `create_note_with_link` publish short-form Notes immediately, because Notes have no draft state on Substack. Treat the Note tools as public-publish actions — there is no preview step and no undo from this server. The split is proportionate review, the piece of trust infrastructure for agents this server cares most about: the high-stakes surface gets a human gate, and the exception is stated loudly.\n\n\n ![\"substack-mcp](\"https://glama.ai/mcp/servers/conorbronsdon/substack-mcp/badge\")
\n\n\n## Tools\n\nEvery tool declares MCP [tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), set **explicitly** rather than left to MCP's defaults (an omitted `destructiveHint` or `openWorldHint` defaults to `true`). Reads carry `readOnlyHint: true`. Draft updates replace existing fields and carry `destructiveHint: true`; additive writes carry `destructiveHint: false`. Draft writes are private (`openWorldHint: false`); `upload_image` carries `openWorldHint: true` because it returns a publicly-fetchable CDN URL; and the Note tools carry `openWorldHint: true` for immediate public publish. Annotations are untrusted hints, so the authoritative wording lives in each tool's description.\n\n### Read\n\n| Tool | Description |\n|------|-------------|\n| `get_subscriber_count` | Get your publication's current subscriber count |\n| `list_subscribers` | Read a bounded page of private subscriber records |\n| `get_subscriber` | Look up membership by exact email; reconcile pending additions |\n| `list_published_posts` | List published posts with pagination |\n| `get_publication` | Read projected publication identity/settings, verify the configured host, and report missing fields; does not verify account identity or role |\n| `list_publication_tags` | Read tag definitions, including hidden tags by default, with bounded local pagination |\n| `get_post_tags` | Resolve post tag associations; preserves unresolved IDs and reports empty-result identity uncertainty. Draft coverage is currently live-verified only for empty responses |\n| `search_posts` | Search a publication archive by query and status; bounded pages with continuation metadata |\n| `plan_draft_update` | Review proposed changes, preflight and a receipt for best-effort stale detection; no writes |\n| `export_draft` | Editable Markdown, exact original body, conversion diagnostics, preflight and editor link |\n| `preflight_draft` | Read-only checks for title, audience, body structure, images, and paywalls, with an editor link |\n| `list_drafts` | List draft posts |\n| `get_post` | Get full content of a published post by ID |\n| `get_draft` | Get full content of a draft by ID |\n| `get_post_comments` | Get comments on a published post |\n| `get_sections` | List your publication's sections (categories) with their IDs |\n| `get_post_analytics` | Get a published post's stats (views, opens, signups, subscribes, reactions) by ID |\n| `list_scheduled_posts` | List posts scheduled for future publication (read-only; scheduling stays in Substack's editor) |\n\n### Archive search and draft review\n\n`search_posts` accepts `query` (1–500 characters), `status` (`published`, `drafts`,\nor `scheduled`, default `published`), `offset` (default 0), and `limit` (1–50,\ndefault 25). It makes one authenticated archive request and returns projected\nmetadata, `returned`, `total`, `has_more`, and `next_offset`. Continue with\n`next_offset` and the same query/status. When Substack omits the total and a\npage is full, `has_more` is null (unknown); another page may be empty. Substack\ncontrols matching and indexing: this is not a guaranteed full-text scan. Use\n`get_post` or `get_draft` to retrieve full content. Pagination is not a snapshot;\nconcurrent edits can move results between pages.\n\n`preflight_draft` accepts `draft_id`, reads it once, and returns `checks_passed`,\nfindings with severity/code/message, content counts and an editor link. It checks title,\naudience, JSON/body shape, image wrappers and HTTPS sources, and paywall count\nand edge placement. Unknown nodes and external images produce review warnings.\nBodies over two million characters, 10,000 nodes, or depth 100 are not fully\nchecked; `counts.complete` is false and aggregate checks are skipped after a\nscan limit. Unknown-node warnings name up to five types for editor review.\nThis is a focused static check, not full ProseMirror validation or\npublish approval. It does not fetch links/images, verify access settings, or\nprove final rendering. Review the draft in Substack; no content is modified.\n\nBoth tools require `publication` when multiple publications are configured.\n\n### Operator diagnostics\n\nThe CLI also exposes read-only workflows through the same MCP handlers:\n\n```sh\nsubstack-mcp status --json\nsubstack-mcp drafts list --limit 10 --offset 0\nsubstack-mcp drafts get 42\nsubstack-mcp drafts export 42 --format json\nsubstack-mcp analytics post 42\nsubstack-mcp subscribers count\nsubstack-mcp subscribers get reader@example.com\n```\n\nAdd `--publication key` when multiple publications are configured. Read commands\nreturn `{format_version: 1, ok, command, publication, data}` as JSON; `--json` is\naccepted explicitly. Exit 0 means a completed read, 1 means a configuration,\nupstream or output failure, and 2 means invalid arguments or selection. A missing\nanalytics result or subscriber is still a completed read; inspect `data`. Counts\nretain their exact/approximate/unavailable precision. Output is capped at 4 MiB\nwithout partial printing. Draft and subscriber output is private.\n\n`status` reports installed version, Node/platform and the same offline\nconfiguration diagnostics as doctor. It never opens a browser or claims a\nverified user identity. `drafts export` is an alias of the existing `export`\ncommand and retains its bundle/overwrite contract. Draft plan/apply also retain\ntheir existing output and exit codes; these aliases do not rewrap saved plans.\n\n```sh\nsubstack-mcp doctor --json\nsubstack-mcp doctor --json --check-auth\n```\n\n`doctor` uses the same environment/stored-session resolution as the server.\nBoth validate an HTTPS publication origin, a positive safe-integer user ID\ncontaining only digits, and an unquoted cookie value without whitespace or\ncookie separators. Invalid configuration stops server startup before requests.\nPercent-encoded cookie values are preserved exactly. Configuration checks do\nnot prove that the supplied host belongs to Substack or that credentials work.\n\nUpgrading: missing or malformed credentials now stop startup instead of\nstarting tools that fail later. Correct all configured publications; invalid\nentries are never silently dropped. `doctor` and `--help` still run without a\nworking session. Use `substack-mcp-login` to set up a first session.\n\nBy default, `doctor` checks configuration without network requests. `--check-auth`\nadds one draft-list GET per valid publication, with a five-second request\ndeadline and redirects disabled. Use an HTTPS publication origin (no path,\nquery, credentials, or custom port); a redirect or custom-domain block may\nrequire switching to the publication's canonical `name.substack.com` origin.\nAll API requests reject redirects, including same-origin redirects, without\nfollowing the destination or replaying a write. The publish-page Referer is\nretained for direct custom-domain requests. Configure the origin that serves\nthe API directly; a redirect response is reported as `redirect_rejected`.\n\nEach request has one deadline through headers and body consumption (30 seconds\nby default, five seconds for `doctor --check-auth`). Streamed response limits\nare 10 MiB for API JSON, 1 MiB for doctor, 2 MiB for the public-page count\nfallback, and 64 KiB for error bodies. Limits apply to bytes delivered by fetch,\nincluding decompressed bytes. Oversized responses fail without partial results.\nFor an oversized HTTP error body, the HTTP error classification is preserved\nand diagnostic details are discarded.\nJSON parsing is synchronous and bounded by input bytes, so it cannot be\ninterrupted mid-parse; a complete parsed result is retained if parsing finishes\nafter the I/O deadline.\nThe public count fallback permits at most three HTTPS redirects within the same\ndeadline. It sends no cookies or authorization and rejects destinations with\nURL credentials or custom ports. It returns unavailable when its read fails.\n\nDoctor distinguishes `unexpected_html`, `malformed_json`, `response_too_large`,\n`redirect_rejected`, `timeout`, `rate_limited`, and `unauthorized_or_blocked`.\nHTTP 401/403/429 bodies are discarded without waiting; rate-limit errors retain\nvalid delta-seconds or standard HTTP-date `Retry-After` guidance. Error details\nare capped at 500 characters (plus an ellipsis) and matching cookie values are\nredacted before truncation. Requests are never automatically retried. A failed\nor timed-out write may have succeeded upstream; reconcile its state before\ntrying again.\n\nOutput includes publication key, origin, credential source, configuration and\nauthentication status. It omits session tokens, user IDs and upstream error\nbodies. A successful read does not establish user-ID binding or write access.\n\nExit codes: 0 = requested checks passed; 1 = configuration/authentication check\nfailed; 2 = invalid command arguments. Without `--check-auth`, a 0 exit code\ndoes not mean the session is unexpired. Bare `substack-mcp` still starts the\nMCP server; `substack-mcp serve` is an explicit alias. `--help` does not connect\nto Substack. Browser login is `substack-mcp login`; `substack-mcp-login` remains an alias.\n\n### Write (private drafts; image upload returns a public URL)\n\n| Tool | Description |\n|------|-------------|\n| `create_draft` | Create a new draft from markdown (private) |\n| `update_draft` | Apply a reviewed change receipt; recheck unpublished state and report readback outcomes |\n| `upload_image` | Upload an image to Substack's CDN — returns a publicly-fetchable (unlisted) URL |\n\n### Publish (Notes — public immediately)\n\n| Tool | Description |\n|------|-------------|\n| `create_note` | Publish a Substack Note (short-form, **publishes immediately**) |\n| `create_note_with_link` | Publish a Note with a link card attachment (**publishes immediately**) |\n\nNotes have no draft state on Substack, so there is no draft-first option for these two tools.\n\n### Subscriber management\n\n`add_free_subscriber` adds one consenting reader to the free newsletter. It is\na distribution change: that reader may receive future newsletter emails. It\ncan request a welcome email with `send_welcome_email: true` (off by default).\nIt never grants paid access or overrides Substack's\nsuppression of previously unsubscribed addresses. Its MCP annotations identify\nit as an external write (`readOnlyHint: false`, `openWorldHint: true`).\n\n```json\n{\"email\":\"reader@example.org\",\"consent_confirmed\":true,\"consent_evidence\":{\"source\":\"booking:message-id\",\"recorded_at\":\"2026-09-01T00:00:00Z\"},\"dry_run\":true}\n```\n\nDry-run is the default. After checking actual newsletter consent, set\n`dry_run: false` to execute. Live adds require the source reference and timestamp\nin `consent_evidence`; this attestation is echoed with the publication key for\nauditing and does not replace checking the underlying consent record.\nMulti-publication configurations also require the\n`publication` selector, just like every other tool.\n\nResults distinguish `existing`, `dry_run`, `verified`, `blocked`, and\n`unverified`, `busy`, and `retryable`. `busy` performs no write; wait for the\nother operation. `retryable` means authentication or rate limiting refused the\nrequest; resolve that condition before explicitly retrying. An empty API acknowledgement is **not** proof of addition.\n`verified` means an exact membership lookup succeeded after the request; it\ndoes not prove that this request originally created the membership. Dashboard\ndata can lag. A missing reader may also have previously unsubscribed.\n\nFor `unverified`, recheck with `get_subscriber`; never automatically repeat the\nadd. For `blocked`, review in Substack without bypassing suppression. Automated\ncallers must persist an attempt ledger **before** sending each live request.\nThe client's in-memory duplicate guard does not survive restarts or separate\nHTTP sessions. Keep subscriber identities and consent evidence out of shared\nrepositories, prompts to unapproved public services, and routine logs.\n\nImplementation and live verification notes: [subscriber API](docs/subscribers.md).\n\nFor Google Calendar booking opt-ins, the [calendar sync helper](docs/calendar-sync.md)\nprovides a bounded Gmail scan, latest-answer selection, a private durable attempt\nledger, and read-only reconciliation after uncertain writes. Scheduling is an\nexplicit local setup step; installing the MCP does not start a background job.\n\n### Intentionally excluded\n\n- **Publish posts** — Publishing long-form posts should be a deliberate human action (Notes are the documented exception above)\n- **Delete** — Too destructive for an AI tool\n- **Schedule** — Use Substack's editor for scheduling. (`list_scheduled_posts` *reads* what you've queued there, but this server never creates, edits, or cancels a schedule.)\n\n## Setup\n\nRequires **Node.js 22 or newer** (CI covers Node 22 and 24). Browser login additionally requires Playwright.\n\nYou can supply credentials two ways: paste them as env vars (below), or run the\noptional **browser login** which captures and stores them for you.\n\n### Option A — Browser login (optional, no manual cookie copying)\n\nInstall the server and optional Playwright dependency together in a local tools\ndirectory, then sign in:\n\n```bash\nnpm install @conorbronsdon/substack-mcp playwright\nnpx playwright install chromium\nnpx substack-mcp login https://yourblog.substack.com --user-id 12345\n```\n\n`substack-mcp-login` remains a supported alias. Missing publication URL and user\nID are prompted. Supply your own account's user ID; a post author's byline does\nnot verify your identity. The browser opens for sign-in, including any CAPTCHA.\nOnly a cookie applicable to the publication API is captured, and a bounded\nauthenticated read must succeed before saving. This verifies read access, not\nthe configured user ID or permission to write.\n\nWithout `--profile`, login saves `~/.substack-mcp/session.json` (directory override:\n`SUBSTACK_MCP_HOME`). The server uses this legacy session when publication\ncredential environment variables and `SUBSTACK_PROFILES` are unset.\n\n**Storage:** sessions use AES-256-GCM with a key derived from the OS account and\nmachine. File permissions request `0600`; Windows access also depends on directory\nACLs. This is a machine-bound file, not an OS keychain or secret vault. Code\nrunning as your OS user can derive the key. Use environment credentials if your\nMCP client manages secrets for you.\n\n#### Named profiles and migration\n\n```bash\nnpx substack-mcp login https://yourblog.substack.com --user-id 12345 --profile work\nnpx substack-mcp profiles list\n# Copy an existing legacy session without changing its file:\nnpx substack-mcp profiles migrate --name personal\n```\n\nKeys start with a lowercase ASCII letter and contain only lowercase letters,\ndigits and hyphens, up to 64 characters. Existing profiles require explicit\n`--force` to replace. List output contains keys, readability status, publication origins and file save\ntimes; it excludes cookies and user IDs. Unreadable profiles remain visible but\ncannot be selected. Save time records local persistence, including migration; it\nis not token issuance or expiration time. Listing is bounded to 32 profiles.\n\nProfile storage requires a local filesystem supporting hard links (such as NTFS\nor a typical Linux filesystem), so creation can install a complete encrypted file\nwithout overwriting an existing name. FAT/exFAT and some network mounts are not\nsupported: set `SUBSTACK_MCP_HOME` to a suitable local directory. Do not use\n`--force` to work around an unsupported filesystem.\n\nSet `SUBSTACK_PROFILES=work,personal` in your MCP client's environment to select\nup to 32 distinct profiles. Remove all publication credential variables first:\ncombining profile selection with legacy or named credential variables is an\nerror, including empty variables. Missing, corrupt or invalid selected profiles\nstop startup; they never fall back to another account. Profiles on disk are\nnever activated by discovery. With multiple profiles, tools require an explicit\npublication key and CLI reads require `--publication`.\n\nTo roll back, unset `SUBSTACK_PROFILES` and restore your previous environment\nconfiguration. Migration preserves the legacy session byte-for-byte. These files\nuse the existing encryption format; an OS keychain is not currently supported.\nRun `substack-mcp status --json` for offline configuration diagnostics or\n`substack-mcp doctor --check-auth --json` for a bounded read per selected account.\n\n### Option B — Get your credentials manually\n\nOpen your Substack in a browser, then:\n\n1. **Session token:** Navigate to your publication, open DevTools → Application → Cookies → copy the value of `connect.sid` (URL-encoded string starting with `s%3A`)\n2. **User ID:** Use the numeric ID of your signed-in Substack account from your authenticated account data. Do not use a publication post's byline ID: publications can have multiple authors. This server does not independently verify the supplied ID.\n3. **Publication URL:** Your Substack URL, including custom domain if you have one (e.g., `https://newsletter.yourdomain.com` or `https://yourblog.substack.com`)\n\n### 2. Configure your MCP client\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"substack\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@conorbronsdon/substack-mcp\"],\n \"env\": {\n \"SUBSTACK_PUBLICATION_URL\": \"https://yourblog.substack.com\",\n \"SUBSTACK_SESSION_TOKEN\": \"your-session-token\",\n \"SUBSTACK_USER_ID\": \"your-user-id\"\n }\n }\n }\n}\n```\n\n[Claude Code and Codex plugin setup](docs/plugins.md) is available alongside\nmanual MCP configuration. The repository marketplace and local plugin are\nseparate from curated-directory acceptance or hosted ChatGPT support.\n\n#### Claude Code\n\nAdd to your `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"substack\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@conorbronsdon/substack-mcp\"],\n \"env\": {\n \"SUBSTACK_PUBLICATION_URL\": \"https://yourblog.substack.com\",\n \"SUBSTACK_SESSION_TOKEN\": \"your-session-token\",\n \"SUBSTACK_USER_ID\": \"your-user-id\"\n }\n }\n }\n}\n```\n\n### 3. Verify\n\nAsk your AI assistant: \"How many Substack subscribers do I have?\"\n\nTool output compatibility, response limits and versioning are documented in\n[the tool contract](docs/tool-contract.md).\n\n## Multiple publications\n\nRunning more than one publication behind a single server? Set a `SUBSTACK_PUB__*` triplet per publication instead of the plain `SUBSTACK_*` vars. `` is any name you choose (letters, digits, underscores) — it becomes the publication's lowercase, hyphenated key, e.g. `KEVIN_MULDOON` → `kevin-muldoon`.\n\n```json\n\"env\": {\n \"SUBSTACK_PUB_KEVIN_MULDOON_PUBLICATION_URL\": \"https://kevinmuldoon.substack.com\",\n \"SUBSTACK_PUB_KEVIN_MULDOON_SESSION_TOKEN\": \"token-1\",\n \"SUBSTACK_PUB_KEVIN_MULDOON_USER_ID\": \"111\",\n \"SUBSTACK_PUB_SAPERE_PUBLICATION_URL\": \"https://sapere.substack.com\",\n \"SUBSTACK_PUB_SAPERE_SESSION_TOKEN\": \"token-2\",\n \"SUBSTACK_PUB_SAPERE_USER_ID\": \"222\"\n}\n```\n\nEach triplet is independent, and setting *any* `SUBSTACK_PUB__*` variable declares that publication. An incomplete triplet — a missing variable, an empty value, or a whitespace-only value — fails startup with an error naming the key, rather than silently dropping that publication. That matters because a dropped publication is not \"one fewer publication\": drop the only one and the server falls back to your stored browser-login session; drop one of two and every tool loses its `publication` parameter, so a call meant for the dropped publication routes silently to the surviving one.\n\nKeys are compared case-insensitively, with `_` folded to `-`. Two names that resolve to the same key (`SUBSTACK_PUB_ALPHA_*` and `SUBSTACK_PUB_Alpha_*`) are a startup error too — merging them silently would let one publication's URL pair with another's session token.\n\n`` accepts ASCII letters, digits, and underscores; the three suffixes must be uppercase and the whole name must have no stray whitespace. Anything that begins with `SUBSTACK_PUB_` but does not fit that shape — a hyphen in the key, a lowercase suffix, an accented character, a trailing space — is a startup error naming the variable, not a variable that gets quietly ignored. For the same reason as above: an ignored publication is not one fewer publication, it is a silent reroute to a different one.\n\nWith two or more publications configured, every tool gains a **required** `publication` parameter — one of your configured keys (e.g. `kevin-muldoon`, `sapere` above). The calling model must specify one on every call; an unrecognized value is rejected before any Substack API call is made, so a stray write can't land on the wrong publication. **With exactly one publication configured** — the common case, whether via plain `SUBSTACK_*` vars or a single `SUBSTACK_PUB__*` triplet — **no `publication` parameter is added at all**; every tool's schema is unchanged from single-publication mode.\n\nDon't mix the two styles: if any `SUBSTACK_PUB__*` var is set, the plain `SUBSTACK_*` vars are ignored (with a startup warning) rather than treated as an unnamed extra publication.\n\n`SUBSTACK_USER_AGENT` and `SUBSTACK_REQUEST_TIMEOUT_MS` apply to every configured publication — they are not per-publication. Browser login also supports explicit named profiles; see [Named profiles and migration](#named-profiles-and-migration).\n\n## Token expiration\n\nSubstack session tokens expire periodically (typically ~90 days). If you get authentication errors, grab a fresh `connect.sid` cookie from your browser and update the env var (make sure ad blockers are disabled when copying the cookie) — or, if you used the browser login, just re-run `substack-mcp-login` to refresh the stored session.\n\n## Custom domains & Cloudflare\n\nSubstack publications served on a custom domain (e.g. `blog.example.com`) sit behind Cloudflare, which can reject non-browser requests with `403 error code: 1010`. To avoid this, the server sends a browser `User-Agent` and a `Referer` by default, and addresses the publication by its canonical `*.substack.com` host.\n\n- **Use the canonical host.** Set `SUBSTACK_PUBLICATION_URL` to the publication's `*.substack.com` address rather than the custom domain. Calls to the canonical host are served directly; custom-domain calls may 301-redirect and then 401.\n- **Override the User-Agent** (optional) via `SUBSTACK_USER_AGENT` if you need a different browser signature:\n\n```json\n\"env\": {\n \"SUBSTACK_PUBLICATION_URL\": \"https://yourblog.substack.com\",\n \"SUBSTACK_SESSION_TOKEN\": \"your-session-token\",\n \"SUBSTACK_USER_ID\": \"your-user-id\",\n \"SUBSTACK_USER_AGENT\": \"Mozilla/5.0 ...\"\n}\n```\n\n## Request timeout\n\nEvery request to Substack is bounded by a 30-second deadline. Node applies no request timeout of its own — only a 10-second *connect* timeout — so a host that accepts the connection and then goes silent (a proxy that drops packets rather than refusing them) would otherwise hang a tool call indefinitely. A request that hits the deadline fails with a `TimeoutError` naming the endpoint and the limit.\n\nRaise or lower it with `SUBSTACK_REQUEST_TIMEOUT_MS` (milliseconds; a non-numeric or non-positive value is ignored with a warning and the default is used):\n\n```json\n\"env\": {\n \"SUBSTACK_REQUEST_TIMEOUT_MS\": \"60000\"\n}\n```\n\n## Transports\n\nBy default the server speaks MCP over **stdio** — the client spawns it as a subprocess per session, which is what the Claude Desktop/Code configs above assume.\n\nFor a persistent, network-reachable deployment (e.g. one server shared by multiple machines, connected to via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)), set `MCP_TRANSPORT=http`. This starts a stateless Streamable HTTP server instead:\n\n- `POST /mcp` — the MCP endpoint\n- `GET /health` — returns `{\"status\":\"ok\"}` for container healthchecks\n\n```bash\ndocker run -d --restart unless-stopped -p 127.0.0.1:8080:8080 \\\n -e MCP_TRANSPORT=http \\\n -e MCP_HTTP_ALLOWED_HOSTS=localhost:8080,127.0.0.1:8080 \\\n -e MCP_HTTP_TOKEN=\"$(openssl rand -hex 32)\" \\\n -e SUBSTACK_PUBLICATION_URL=https://yourblog.substack.com \\\n -e SUBSTACK_SESSION_TOKEN=your-session-token \\\n -e SUBSTACK_USER_ID=your-user-id \\\n substack-mcp\n```\n\n`MCP_HTTP_PORT` (default `8080`) and `MCP_HTTP_HOST` (default `0.0.0.0`, which is what makes a container reachable through `-p`) configure the listener. Each request gets its own server instance — there's no session state kept between requests, so nothing to lose if the container restarts.\n\n### What this listener will accept\n\nOver stdio the trust boundary is your user account. Over HTTP it is whatever can open a socket to the port — and every request that gets through carries your Substack session cookie, including `create_note`, which publishes immediately with no undo. The listener therefore starts closed and is opened deliberately:\n\n| Variable | Default | Effect |\n|---|---|---|\n| `MCP_HTTP_ALLOWED_HOSTS` | loopback names for the bound port | Comma-separated `Host` allowlist. A request whose `Host` is not listed gets `403`. `*` disables the check. |\n| `MCP_HTTP_ALLOWED_ORIGINS` | loopback origins for the bound port | Comma-separated `Origin` allowlist; `403` otherwise. A request with **no** `Origin` is always allowed — non-browser MCP clients don't send one. `*` disables the check. |\n| `MCP_HTTP_TOKEN` | unset | When set, requires `Authorization: Bearer `; `401` otherwise. |\n| `MCP_HTTP_MAX_BODY_BYTES` | `10485760` (10 MiB) | Hard cap enforced while the body streams. Over-limit requests get `413`. |\n\nEvery one of these is checked before the request is handed to an MCP server, so a rejected request never reaches the Substack API.\n\nOnly origin-form request targets are served (`POST /mcp`, `GET /health`). An absolute-form target (`POST http://elsewhere/mcp`), a scheme-relative one (`POST //elsewhere/mcp`), or a malformed one all get `400` — none of them are routed, and none can take the process down.\n\n**Reaching the server under any name other than loopback requires setting `MCP_HTTP_ALLOWED_HOSTS` yourself.** That is the DNS-rebinding defence: without it a page in your browser can resolve an attacker-controlled name to `127.0.0.1` and drive this server as you.\n\n**Host and Origin checks are not authentication.** They stop a browser being used as a confused deputy; they do nothing about a process running on the same host, which can set any `Host` it likes and send no `Origin` at all. On a machine where anything else runs — another MCP server, a dev container, a shared box — set `MCP_HTTP_TOKEN`. Publish the port to `127.0.0.1` rather than every interface (`-p 127.0.0.1:8080:8080`), and put the service behind a VPN or private network as you would any other credentialed internal service.\n\n## Typed errors\n\nAPI failures are mapped to a typed error hierarchy (`SubstackAPIError` base, with `AuthenticationError`, `RateLimitError`, `ValidationError`, `NotFoundError`, and `ServerError` subclasses keyed off HTTP status) in `src/utils/errors.ts`. Every tool call still surfaces the same error response shape on failure — the typed hierarchy just makes the message specific to what went wrong instead of a single generic \"Substack API error\" string.\n\n| Class | Status | Triggered by |\n|---|---|---|\n| `AuthenticationError` | 401/403 | Expired/invalid session token, or a Cloudflare `error code: 1010` block (see above) |\n| `RateLimitError` | 429 | Too many requests against the Substack API in a short window |\n| `ValidationError` | 400 | Malformed or invalid arguments passed to a tool (e.g. a missing required field) |\n| `NotFoundError` | 404 | The referenced draft, post, or note doesn't exist |\n| `ServerError` | 5xx | Failure on Substack's side |\n| `TimeoutError` | 408 (synthetic) | The request hit the client's own deadline — no response arrived, so there is no real status to report (see [Request timeout](#request-timeout)) |\n| `SubstackAPIError` | any other status | Fallback for unmapped status codes |\n\nSubstack error response bodies are inconsistent — sometimes JSON (`{\"error\": \"...\"}` or `{\"errors\": [...]}`), sometimes plain text, and sometimes a large Cloudflare HTML block page. `extractErrorDetail` handles all three: it tries `JSON.parse` first, falls back to the raw text (trimmed and capped at ~500 characters so a multi-KB HTML page doesn't become the whole error message), and only uses a generic fallback string if the body is empty.\n\n## Draft export\n\nUse `export_draft` for a read-only Markdown/JSON bundle, or run:\n\n```sh\nsubstack-mcp export 42 --output draft-export.json\nsubstack-mcp export 42 --format markdown --output draft.md\n```\n\nMarkdown exports retain the exact original body in a `.source.json` sidecar.\nInspect `unsupported_nodes` before reuse. Existing files require `--force`.\nSee [export and CLI behavior](docs/export.md) for publication selection, limits,\npartial exports and file recovery.\n\n## Markdown support\n\nDrafts accept CommonMark/GFM Markdown: headings, nested bold/italic/strikethrough,\nlinks and reference links, images with captions and linked destinations, nested\nlists with starting numbers, code, blockquotes, rules and hard breaks. A standalone\n`` block adds one paywall to a long-form draft.\n\nUnsupported content returns `unsupported_nodes` before a write. After reviewing\nthose diagnostics, draft callers can explicitly set `allow_unsupported: true`\nto retain literal fallbacks. Tables remain Markdown inside code blocks; native\ntables, footnotes, callouts and arbitrary embeds are not advertised as supported.\nNotes reject unsupported conversion before either publication or attachment\ncreation and have no fallback override.\n\nSee [Markdown authoring](docs/authoring.md) for mappings, limits, compatibility\nchanges and the distinction between offline fixtures and live editor checks.\n\n## Important notes\n\n- This server uses Substack's **unofficial API**. It may break if Substack changes their endpoints.\n- Session tokens are sent as cookies. Keep your `SUBSTACK_SESSION_TOKEN` secure.\n- The server checks your credentials on startup, *after* the MCP handshake completes, and only warns — it never blocks startup on a network call. Tools still error individually if the token is expired, which is where the failure is actionable.\n- `SIGTERM` and `SIGINT` are handled: the server closes its transport and exits 0, so `docker stop` returns promptly instead of waiting out the grace period.\n\n## Development\n\nFor opt-in live read checks, see [live contract evidence](docs/live-contract-evidence.md).\nThe probe is disabled in ordinary CI and never publishes or writes.\n\nBefore releasing, run `npm run test:package`. It installs the built tarball with production dependencies in a clean temporary directory, checks both executable entrypoints, and verifies the MCP version and the complete registered tool catalog without real credentials.\n\n```bash\ngit clone https://github.com/conorbronsdon/substack-mcp.git\ncd substack-mcp\nnpm install\nnpm run build\n```\n\nRun locally:\n```bash\nSUBSTACK_PUBLICATION_URL=https://yourblog.substack.com \\\nSUBSTACK_SESSION_TOKEN=your-token \\\nSUBSTACK_USER_ID=your-id \\\nnpm start\n```\n\n## Contributing\n\nIssues and pull requests are welcome. Because this server uses Substack's unofficial API, the most useful contributions are fixes when an endpoint changes. If a tool stops working, open an issue with the tool name and the error. The safe-by-design boundary stays: no publish, no delete, no schedule for long-form posts. Notes publish immediately by design and must keep saying so loudly in their descriptions.\n\n## About\n\nBuilt and maintained by [Conor Bronsdon](https://github.com/conorbronsdon) for the [Chain of Thought](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=substack-mcp) podcast production workflow, where it drafts and reviews newsletter posts before a human hits publish. Conor hosts Chain of Thought, a show about AI infrastructure and how practitioners actually build with it. More tools for creators live in [ai-tools-for-creators](https://github.com/conorbronsdon/ai-tools-for-creators). Find Conor on X at [@ConorBronsdon](https://x.com/ConorBronsdon).\n\n**Companion tools:**\n- [Transistor-MCP](https://github.com/conorbronsdon/Transistor-MCP): manage podcast episodes, analytics, and transcripts on Transistor.fm\n- [podcastindex-mcp](https://github.com/conorbronsdon/podcastindex-mcp): search the Podcast Index and track guest appearances\n- [op3-mcp](https://github.com/conorbronsdon/op3-mcp): report downloads, listener geography, and apps from OP3\n- [apple-podcasts-mcp](https://github.com/conorbronsdon/apple-podcasts-mcp): pull plays, followers, and per-episode listening from Apple Podcasts Connect\n- [gsc-mcp](https://github.com/conorbronsdon/gsc-mcp): query search performance, keywords, and sitemaps in Google Search Console\n- [podcast-benchmark](https://github.com/conorbronsdon/podcast-benchmark): benchmark a show against its peers using only public data\n\n---\n\n## Disclaimer\n\n*This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.*\n\n## Codex plugin\n\nThe repository includes a Codex manifest at `.codex-plugin/plugin.json` and an\nMCP configuration at `.mcp.json`. It runs the published npm package over stdio\nusing `npx`; Node.js and npm must be available. The package version is pinned\nin `.mcp.json`, so upgrading the plugin's server is an explicit change.\n\nConfigure your Substack credentials outside the plugin using the environment\nvariables or browser-login session described above. Never commit a session\ntoken. Installation does not authenticate an account or grant approval to post.\nLong-form posts remain drafts; Notes publish immediately.\n\n## License\n\nMIT\n\nFor an always-on scheduler with durable cloud state and weekly email reports, see [Cloud Calendar sync](docs/cloud-calendar-sync.md).\n\n### Review before changing a draft\n\nIn 0.9, call `plan_draft_update`, review its output, then call `update_draft` with\nthe same fields and returned receipt. Published or known stale drafts are\nrejected. The read/write race remains; check readback outcomes and review in\nSubstack. The CLI shares this flow through `drafts plan` and `drafts apply`.\nSee [draft changes and migration](docs/draft-changes.md) for examples and limits.\n\nVersioned GHCR images and transport verification: [container distribution](docs/containers.md).\n",
"bytes": 37061,
"sha": "ad730388a0b665dd307055329b5810d57192d0d6c9549ceb3d691d856b62f83b",
"repo_slug": "conorbronsdon/substack-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_conorbronsdon_substack_mcp_bc13774a/readme"
}