MCP server Substack MCP CLI

Substack MCP Server & CLI

Substack MCP server and CLI for Claude Code, Codex and AI agents. 65 tools for drafts, posts, Notes, subscribers, analytics, tags, comments, and researching other writers.

One install gives you both surfaces, the same tools under the same names, covering everything the dashboard does and several things it cannot.

Substack has no public API, which is why your assistant cannot see any of it, and why most things that claim to connect publish posts with the HTML tags showing.

This one speaks Substack's own document format. Ask for a draft and you get a draft, with the YouTube link as a player and the paywall where you put it.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

substack-cli in your terminal, for scripting, cron, pipes, or a quick question without opening anything:

substack-cli                                          # every command, one line each
substack-cli list-drafts                              # what you have in progress
substack-cli get-dashboard-summary                    # subscribers, revenue, recent posts
substack-cli rank-posts --limit 10                    # your best performing posts
substack-cli research-creator-posts --handle someone  # study another writer
substack-cli create-draft --title "Draft" --body "..."
substack-cli <command> --help                         # what any command takes

--confirm is the shell spelling of the confirmation that publishing, deleting and posting Notes require. --json gives JSON, --compact puts it on one line, and errors are JSON on stderr whichever you pick.

substack-cli schema <command> prints the exact JSON Schema an MCP client receives for that tool, which is how you can check the two surfaces really are one thing.

MCP server, for your AI app

substack-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch. You never run it by hand:

claude mcp add substack \
  -e SUBSTACK_PUBLICATION_URL=example.substack.com \
  -e SUBSTACK_SESSION_TOKEN=xxxxx \
  -- npx -y @thenavidm/substack-mcp-cli

Then just ask: "which post drove the most paid conversions last month?"

Each publish, delete, Note and comment waits for your approval in the client, as section 8 explains.

Which one

Where you are	What you can reach
An agent that can run shell commands, like Claude Code or Cursor	Both. The CLI is the cheaper one: it costs nothing until you type it
claude.ai, the Claude Desktop chat tab, or a phone	The server only. There is no shell to run a command in
A terminal, a script, cron or CI	The CLI only. There is no MCP client in a shell

They are the same program reading the same tool definitions, so anything one can do, the other can.

Features

Every tool is both a command and an MCP tool, with the same name. The command is the tool name with dashes.

Capability	CLI command	MCP tool
Drafts	substack-cli list-drafts / get-draft / create-draft / update-draft / delete-draft	list_drafts / get_draft / create_draft / update_draft / delete_draft
Publish or schedule a draft	substack-cli publish-draft / schedule-draft / unschedule-draft / list-scheduled-posts	publish_draft / schedule_draft / unschedule_draft / list_scheduled_posts
Bodies in Substack's own format	substack-cli set-draft-body / preview-draft-body	set_draft_body / preview_draft_body
Published posts and their numbers	substack-cli list-posts / get-post / get-post-by-id / search-posts / get-post-stats / rank-posts	list_posts / get_post / get_post_by_id / search_posts / get_post_stats / rank_posts
Notes, now or later	substack-cli publish-note / publish-note-with-link / schedule-note / list-scheduled-notes / cancel-scheduled-note / list-notes / delete-note	publish_note / publish_note_with_link / schedule_note / list_scheduled_notes / cancel_scheduled_note / list_notes / delete_note
Subscribers	substack-cli list-subscribers / export-subscribers / get-subscriber-count / add-subscriber	list_subscribers / export_subscribers / get_subscriber_count / add_subscriber
Analytics	substack-cli get-analytics / get-dashboard-summary / get-email-stats / get-growth-sources / get-revenue-summary	get_analytics / get_dashboard_summary / get_email_stats / get_growth_sources / get_revenue_summary
Tags	substack-cli list-publication-tags / create-tag / get-post-tags / add-tag-to-post / remove-tag-from-post	list_publication_tags / create_tag / get_post_tags / add_tag_to_post / remove_tag_from_post
Comments	substack-cli get-post-comments / comment-on-post / delete-comment / get-comment-thread	get_post_comments / comment_on_post / delete_comment / get_comment_thread
Reading Substack	substack-cli list-subscriptions / list-reader-posts / get-reader-post / get-reader-feed / get-profile-feed / restack-note	list_subscriptions / list_reader_posts / get_reader_post / get_reader_feed / get_profile_feed / restack_note
Your publication	substack-cli get-publication-settings / update-publication-settings / get-sections / list-contributors / get-import-status	get_publication_settings / update_publication_settings / get_sections / list_contributors / get_import_status
Templates	substack-cli list-templates / create-template / delete-template / create-draft-from-template	list_templates / create_template / delete_template / create_draft_from_template
Research other writers	substack-cli research-creator-posts / research-creator-notes / compare-publications / scrape-post / search-publications / get-publication-info / get-user-profile	research_creator_posts / research_creator_notes / compare_publications / scrape_post / search_publications / get_publication_info / get_user_profile
Images	substack-cli upload-image	upload_image
Check your setup	substack-cli doctor	not a tool

All 65 with their arguments are in section 7.

Contents

#	Section	What is in it
1	What you can ask it	Real prompts, not features
2	Quick install	One line, no account needed
3	Setup	Getting your session cookie
4	Connect your client	Claude, Cursor, Windsurf, the rest
5	Check it worked	And the two things that fail
6	Which surface, and what each costs	Measured in Claude Code, and how to spend less
7	Tools	All 65, grouped by what they reach
8	Writing safely	What is guarded and what is not
9	Writing posts	Markdown, embeds, paywalls
10	Your data	What is stored, and where
11	Troubleshooting	When something breaks
12	FAQ	The questions people actually ask

1. What you can ask it 💬

• Draft this week's post from my notes, in the voice of my last five.
• Which of my posts got the most paid conversions, and what do they have in common?
• How many subscribers have not opened anything in 90 days?
• Pull every Note that mentions pricing from the three writers I compete with.
• Add a paywall after the third section of that draft.
• Schedule this Note for 9am Tuesday.
• Compare my open rate to what it was six months ago.
• Read my inbox and tell me what my corner of Substack is arguing about this week.
• Turn my last three posts into a guide, and put the YouTube version at the top.

The last one is the point. It reads your existing posts, writes a new draft in your format, and embeds the video as a real player rather than a blue link, because it speaks Substack's document format rather than pasting HTML at it.

2. Quick install ⚡

Node 22 or newer. Nothing else.

npx -y @thenavidm/substack-mcp-cli@latest --version

That is the whole install. npx fetches it on demand, so there is nothing to update later.

Installing the package needs no account. Only connecting it does, which is the next section.

Before you start

You need	Check with	If missing
Node 22 or newer	node -v	nodejs.org
A Substack publication you own	Open your publication's dashboard	Start one at substack.com, it is free
Its canonical address	It ends .substack.com	Custom domains do not serve the API, see below

[!IMPORTANT] Use the yourname.substack.com address, not a custom domain. Substack does not serve its API on custom domains: the request redirects and ends in a 404.

3. Setup 🔑

Substack has no public API and no OAuth. Everything here runs on your browser session cookie, exactly like the Substack tab you already have open.

Treat that cookie like a password. It is full access to your account. Never paste it into an issue, a gist, or a chat with anyone.

Option A: paste the cookie (fastest, recommended)

npx @thenavidm/substack-mcp-cli@latest login

It asks for your publication URL and the cookie, resolves your user id, and stores the result encrypted. Then you can leave the env block out of your client config entirely.

To find the cookie:

1. Open your publication and sign in.
2. DevTools, then Application, then Cookies.
3. Copy the value of connect.sid. It is long and starts with s%3A.

Turn off ad blockers first. Some of them strip the cookie from that panel.

Option B: read it from the Chrome you already have open

npx @thenavidm/substack-mcp-cli@latest login --playwriter

Uses Playwriter to read the cookie out of your running Chrome, where you are already signed in. No browser launch, no sign-in, no CAPTCHA. Requires Playwriter and its extension.

Option C: launch a browser and sign in

npm i -g playwright && npx playwright install chromium
npx @thenavidm/substack-mcp-cli@latest login --playwright

A browser opens and waits up to ten minutes for you to sign in, CAPTCHA and emailed link included. This is much the slowest option, and the only one that works on a machine with no Chrome, or in CI.

Playwright is not bundled. It is large, it is only ever used by this one command, and the server never loads it, so your tool calls are not slower for it existing.

Or just use environment variables

Nothing above is required. Set SUBSTACK_PUBLICATION_URL and SUBSTACK_SESSION_TOKEN and you are done. SUBSTACK_USER_ID is optional and looked up automatically when absent.

When it expires

Sessions do expire, commonly reported at around 90 days, though I have not measured it. When calls start failing with an authentication error, run login again, or paste a fresh cookie. doctor warns you once a stored session passes 75 days.

4. Connect your client 🔌

The long version, every step with what to do when one fails, is in INSTALL.md.

Every block below is complete on its own. Pick your client, paste, done.

Replace example.substack.com with your publication and your-connect-sid-value with the cookie from section 3.

Claude Code

claude mcp add substack \
  -e SUBSTACK_PUBLICATION_URL=example.substack.com \
  -e SUBSTACK_SESSION_TOKEN=your-connect-sid-value \
  -- npx -y @thenavidm/substack-mcp-cli@latest

Run /mcp inside Claude Code and substack should be listed. Remove it later with claude mcp remove substack.

Claude Desktop

The quickest route is the extension: download the .mcpb and double-click it. It carries its own dependencies and asks for your publication and cookie in a form, so there is no config file to edit.

To wire it up by hand instead, open Settings, then Developer, then Edit Config. That reveals claude_desktop_config.json. Or go straight there:

System	Config file
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "substack": {
      "command": "npx",
      "args": ["-y", "@thenavidm/substack-mcp-cli@latest"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "example.substack.com",
        "SUBSTACK_SESSION_TOKEN": "your-connect-sid-value"
      }
    }
  }
}

If the file already has other servers, add only the "substack" block inside "mcpServers" and put a comma after the entry before it. One bad comma stops every server loading, not just this one.

Then quit Claude Desktop completely and reopen it. On macOS use Cmd+Q, closing the window is not enough. It only reads that file at startup.

[!TIP] Claude Desktop does not inherit your shell PATH, so if npx is not found, run which npx and use that absolute path as command.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one. Same JSON as above. Reload the window afterwards.

Windsurf

~/.codeium/windsurf/mcp_config.json. Same JSON. Reload afterwards.

VS Code

.vscode/mcp.json in a project, or run MCP: Add Server from the command palette.

Anything else

Zed, Cline, Continue and any other MCP client over stdio all work. They each want the same three things: command, args, and env.

Docker

No image is published, so build it from this repository:

docker build -t substack-mcp-cli .
docker run -i --rm \
  -e SUBSTACK_PUBLICATION_URL=example.substack.com \
  -e SUBSTACK_SESSION_TOKEN=your-connect-sid-value \
  substack-mcp-cli

Self-hosted over HTTP

Only one thing needs this: schedule_note publishes from the machine the server runs on, so a Note queued for 9am fires only if that machine is awake. Everything else is fine on a laptop.

substack-mcp --http --port=8788

It binds to 127.0.0.1, serves /health, and refuses browser requests from other sites unless SUBSTACK_HTTP_ALLOWED_ORIGINS lists them. To reach it from elsewhere set SUBSTACK_HTTP_HOST=0.0.0.0 and SUBSTACK_HTTP_TOKEN to a random string, and put it behind TLS; it will not start on another address without the token. 2.2's SUBSTACK_MCP_* names still work.

[!CAUTION] The HTTP transport holds a live credential for your Substack account. Binding it beyond localhost without a token hands your account to anyone who finds the port.

5. Check it worked 🩺

npx @thenavidm/substack-mcp-cli@latest doctor

doctor runs the checks in order and names the actual problem, rather than leaving you to guess which of six things is wrong.

Two things account for almost every failure. Node is not on the PATH your client sees, which the tip above covers. Or the session cookie is wrong or expired, which doctor names directly.

6. Which surface, and what each costs

Both surfaces are the same program with the same 65 tools. The difference is when the model pays for them. Measured in Claude Code:

Cost	MCP server	CLI
Every message, with every tool loaded	22,800 tokens	nothing
Every message, Claude Code's default	1,210 tokens	nothing
When Substack comes up	nothing more, or the tools it picks	2,360 tokens for SKILL.md, once
20 messages with Substack in 1, every tool loaded	456,000 tokens	2,360 tokens

Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Substack comes up or not. With the skill added, Claude Code also lists its one-line description, about 140 tokens.

Where the tokens go, with every tool loaded:

Part of the tool list	Share
Structure: names, types, required lists, nesting, annotations	44%
Argument descriptions	37%
Tool descriptions	19%

To spend less, turn the server off when you are not using it, which in Claude Code is the /mcp panel. SUBSTACK_READ_ONLY=1 takes the 24 write tools off the list, leaving 41. Or install the CLI and add the server on the days it earns its place.

Measured on 2026-10-05 with Claude Code 2.1.286 on Claude Opus 5.5: one short prompt with and without the server connected, once with ENABLE_TOOL_SEARCH=false and once with the default, the difference read from the API's own usage figures. SKILL.md was measured the same way. Other apps and models count tokens a little differently.

Against 2.2.3, measured the same day: every tool loaded costs 22,833 tokens instead of 25,215, tool search the same, and SKILL.md 102 more, because it now names all ten commands that need --confirm, says how approval works over MCP and lists every exit code. In Codex 0.159.3 on gpt-6.1-sol, the same task, "find the command that schedules a Note to publish later and the flags it requires", read a median of 83,422 input tokens on 3.0.0 against 105,216 on 2.2.3 over the CLI, and 48,510 against 48,534 over MCP, five runs each. 2.2.3's help listed no commands, so the model matched 3.0.0 only in the two runs where it guessed schedule-note blind; in the other three it read the full list or ran a command that does not exist.

7. Tools 🛠️

65 tools. Every one declares whether it reads, writes, or does something that cannot be undone, so your client can show you the difference before anything runs.

Every publication-scoped tool takes an optional publication argument to pick which connected Substack it acts on. See Several publications.

Drafts

Tool	Risk	What it does
create_draft	write	Create a draft from markdown. Private until you publish
update_draft	write	Change any field. Only what you pass is touched
get_draft	read	Read a draft, body returned as markdown you can edit
list_drafts	read	Unpublished drafts, most recently edited first
delete_draft	destructive	Permanent, no trash. Needs confirm
publish_draft	destructive	Publishes and emails your list. Needs confirm
schedule_draft	write	Schedule on Substack's side, so it fires without you
unschedule_draft	write	Back to a plain draft
list_scheduled_posts	read	What is queued, soonest first
set_draft_body	write	Replace the body with a document you build node by node
preview_draft_body	read	See what a body will render as, changing nothing
get_sections	read	Section ids, which create_draft needs

create_draft takes title, subtitle, body, body_format, section_id, audience (everyone, only_free, only_paid, founding), type (newsletter, podcast, thread), cover_image, and three SEO fields.

get_draft takes body_format of markdown, prosemirror, or both. Markdown is the default, because it is what you can actually edit and send back.

Posts

Tool	Risk	What it does
list_posts	read	Published posts, newest first
get_post	read	Read a post by slug, from any publication
get_post_by_id	read	Same, by numeric id
search_posts	read	Search your own posts by keyword
get_post_stats	read	Opens, clicks, views, signups, reactions for one post
rank_posts	read	Rank posts by any metric, to find what worked

Notes

Notes have no draft state on Substack. Writing one publishes it, immediately and publicly.

Tool	Risk	What it does
publish_note	destructive	Live and public at once. Needs confirm
publish_note_with_link	destructive	With a link preview card. Needs confirm
schedule_note	write	Queue one for later. See the caveat below
list_scheduled_notes	read	What is queued, published, failed, cancelled, or to check
cancel_scheduled_note	write	Cancel before it fires
list_notes	read	Notes you have published
delete_note	destructive	Permanent. Needs confirm

Substack's own composer can schedule a Note. This queue adds scheduling from your AI tool or the command line, in batches, with a list you can check and cancel. The server publishes each Note when it comes due.

That only happens while a server is running. A Note set for 9am fires at 9am if your machine is awake with your client open. Otherwise it goes out on the next start after that time, flagged as published late. For scheduling that does not depend on your laptop, see self-hosted over HTTP, or schedule the Note in Substack's composer.

Each Note goes out once. Every AI tool you open runs its own copy of this server, and they share one queue, so a Note is claimed before it is sent and no other copy sends it again. If Substack cannot be reached, it tries again after 1, 5 and 15 minutes. If a send gets no answer, Substack may have published it anyway, so it is marked check for you to look at, never sent a second time. A queue file that cannot be read is kept, with a copy, and reported; nothing in it is overwritten.