Substack MCP Server

Substack MCP Server

A Model Context Protocol (MCP) Server for Substack enabling LLM clients to interact with Substack's API for automations like creating posts, managing drafts, and more.

Create and publish posts, work with subscribers and analytics, browse your reader feeds, manage tags and comments, and upload images — 27 tools exposed through one MCP server.

[!IMPORTANT]

Substack does not provide a public API for these operations. This server uses your authenticated

web session. Treat the session token exactly like a password: keep it local, never commit it, and

never include it or a complete Cookie header in a bug report.

Quick start

The fastest installation uses Node.js 22 or newer and npx.

1. Collect your Substack credentials

Sign in to Substack in your browser and open your publication dashboard. You need three values:

• Publication URL — the full base URL of your publication, for example https://your-publication.substack.com.
• Session token — open your browser's developer tools, select Network, filter to Fetch/XHR, and reload the dashboard. Open a successful authenticated request to your publication. Under Request Headers, find the Cookie header and locate a session cookie named substack.sid or connect.sid. Copy its value without the cookie name or the rest of the header. If both names appear with different values, test them separately and locally with the read-only verification in step 3; never paste either value into an issue.
• User ID — in the same Network panel, search for a successful publication_user request. In its JSON response, copy the numeric id inside the user object.

If the browser UI differs, the illustrated credential guide shows the same requests. If authentication later stops working, sign in again and repeat these steps to obtain the current token.

2. Add the server to your MCP client

For clients that accept MCP JSON configuration, add:

{

"mcpServers": { "substack": { "command": "npx", "args": ["-y", "substack-mcp@latest"], "env": { "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com", "SUBSTACK_SESSION_TOKEN": "your-session-token", "SUBSTACK_USER_ID": "your-user-id" } } } }

Replace the three example values, save the configuration, and restart your MCP client. Consult your client's documentation if it uses a different configuration format.

3. Verify the connection

Ask your client:

List my five most recent Substack drafts.

The client should call list_posts with status: "drafts". If it fails, check the client's MCP logs and the logging section below before opening an issue.

Docker quick start

To use the published Docker image instead of Node.js, add this server configuration:

{

"mcpServers": { "substack": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SUBSTACK_PUBLICATION_URL", "-e", "SUBSTACK_SESSION_TOKEN", "-e", "SUBSTACK_USER_ID", "marcomoauro/substack-mcp:latest" ], "env": { "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com", "SUBSTACK_SESSION_TOKEN": "your-session-token", "SUBSTACK_USER_ID": "your-user-id" } } } }

🛠 Available Tools

create_draft_post - Create a draft post

Inputs:

• title (string): Title of the post
• subtitle (string): Subtitle of the post
• body (string): Body of the post. Plain text becomes one paragraph per line — Markdown is not interpreted, so ## Heading arrives literally. A JSON string of a Substack document also works and is validated against the same schema set_post_body publishes, so an unrecognised node name is an error rather than a silently mangled post.

Returns: {draft_id, is_published}. Pass draft_id to get_draft to read the draft back.

For anything structured — headings, lists, links, code, images, a paywall — use set_post_body after creating the draft: the schema is published there, so the calling model can read the node vocabulary rather than guess at it.

list_subscribers - List and filter your subscribers

Exposes the same filtering the Subscribers dashboard offers: 48 columns, 18 operators, free-text search, sorting and pagination.

Inputs:

• filters (array, optional): conditions combined with AND, each {column, operator, value}
• search (string, optional): free text matched against subscriber name and email
• sort_by (string, optional): any filterable column
• sort_direction (asc | desc, optional): defaults to desc
• limit (number, optional): 1–100, defaults to 25
• offset (number, optional): for paging

Which operators a column accepts depends on its type:

The columns cover subscriber identity (name, email, country, state, group membership), subscription (type, start/expiry/cancel dates, revenue, Stripe plan, attribution), email engagement (opens and unique opens over 7d/30d/6mo, links clicked, sections) and site engagement (post views, unique posts seen, comments, shares, days active, activity rating). The full list with types reaches the client in the tool's JSON Schema, so a model does not have to guess names.

Returns: {count, returned, limit, offset, subscribers}. count is the total matching the filters regardless of limit, so a call with limit: 1 is a cheap way to size a segment.

Note: engagement columns can be *filtered* on here but are not part of the records this tool

returns — Substack takes the fields it returns from the publication's saved Display settings and

ignores a per-request column list. Use `export_subscribers` to read their values.

There is no OR and no nesting: anything needing OR has to be issued as separate calls.

export_subscribers - Export subscribers with every column value

The way to actually *read* the engagement metrics list_subscribers can only filter on: email opens over 7d/30d/6mo, unique emails seen, post views, unique posts seen, comments, shares, links clicked, days active and activity rating.

Inputs:

• filters (array, optional): the same conditions as list_subscribers, combined with AND
• search (string, optional): free text matched against subscriber name and email
• columns (array, optional): which columns to include, defaulting to all of them
• max_wait_seconds (number, optional): 1–600, defaulting to 120

Returns: {count, columns, missing_columns, unmapped_columns, export_id, subscribers}, where each subscriber is keyed by column name.

Substack generates the file asynchronously, so the tool creates a subscriber set, requests the export, polls until it is ready and downloads it. A small export lands in a few seconds. If the wait budget runs out the tool says so and names the export_id rather than blocking.

Two caveats, both verified against the live API:

- tag_ids and group_membership cannot be exported. Substack drops them silently rather

than failing, so they are reported in missing_columns — asking for all 48 columns returns 46.

- Values arrive display-formatted, not raw: revenue is "€50.00" here and the number 50

through list_subscribers. Dates are ISO strings.

There is no paging: an export covers the whole matching set.

list_posts - List drafts, published or scheduled posts

Inputs:

• status (drafts | published | scheduled): which list to read
• search (string, optional): free text matched against title and content
• limit (number, optional): 1–100, defaults to 25
• offset (number, optional): for paging
• sort_direction (asc | desc, optional): drafts and published posts are newest-first, scheduled posts soonest-first

Returns: {status, total, returned, limit, offset, posts}, each post summarised — use get_draft for the full content of an unpublished one.

get_draft - Read one draft in full

Inputs:

• draft_id (number): the id returned by list_posts or create_draft_post

Returns: the draft as Substack stores it, body and audience/email settings included.

set_post_body - Replace a draft's body with a structured document

The only way to write structured content: headings, lists, links, code blocks, quotes, images, buttons and a paywall. create_draft_post takes plain text; this takes the document Substack actually stores, and its schema is published in tools/list so the calling model can read the node vocabulary instead of guessing.

Inputs:

• draft_id (number): the id returned by list_posts or create_draft_post
• body (object): a Substack ProseMirror document — {type: 'doc', content: [...]}

Fifteen node types are accepted: paragraph, heading, bullet_list, ordered_list, list_item, blockquote, highlighted_code_block, code_block, horizontal_rule, captionedImage, button, paywall, youtube2, plus digestPostEmbed, substack_mentions and directMessage passed through unchanged so a document read with get_draft can be written back. Marks: strong, em, code, strikethrough, link.

Returns: {draft_id, nodes}, where nodes counts what was stored by type — so a caller that asked for a paywall can confirm there is one. Validation cannot report a node that was never sent.

Three things worth knowing:

• An image must already be hosted by Substack. image2.src pointing at an external URL is stored but does not render. Use upload_image to re-host one and get a src that works.
• A document may contain at most one `paywall`. Substack accepts two and renders both, leaving it undefined which one cuts the post, so this tool refuses the second.
• `ordered_list` numbers from `attrs.order`, not `attrs.start`. A list given only start renders from 1 with no error.

upload_image - Host an image on Substack, from a URL or a local file

Substack's editor uploads images as base64 data URIs to POST /api/v1/image, which answers with a Substack-hosted URL. image2.src in set_post_body and cover_image in update_draft only render such a URL, so this tool is the bridge. Substack itself only re-fetches URLs already in its own storage, so the image is encoded here rather than being handed off.

Inputs — exactly one of url or path:

• url (string): the http(s) URL of an image to download and re-host
• path (string): absolute path to an image file on the machine running this server, read straight from disk with no download
• post_id (number, optional): the post the image belongs to; its effect is unconfirmed

Returns: {id, url, content_type, bytes, width, height} — put url into an image2.src when calling set_post_body, or into cover_image when calling `update_draft