Substack Publisher MCP

What dkships/substack-publisher-mcp MCP server does

The dkships/substack-publisher-mcp MCP server exposes read-only Substack Publisher API data through MCP tools. It can enumerate configured publications, retrieve published posts, inspect post-level engagement, report daily subscriber totals by category, and find a subscriber by email address.

The server is intended for querying publication data rather than publishing or editing content. Available post data includes fields such as title, audience, subtitle, publication date, URL slug, and cover image. Post statistics can include opens, clicks, recipients, views, new free subscriptions, new paid subscriptions, and estimated revenue increase. Subscriber count responses can distinguish totals such as paid, free-trial, comp, gift, lifetime, and founding subscribers.

How it works

The server communicates with Substack's official Publisher API and authenticates with an API key. It does not rely on browser cookies or an unofficial internal API. The project is community-developed and is not affiliated with, endorsed by, or supported by Substack.

Each MCP tool except list_publications accepts an optional publication selector. This allows one process to serve several publications when each has its own configured API key. list_posts supports date ranges, sorting, post type, result limits, and pagination through a continuation value. The post lookup and statistics tools use a post's URL slug, while subscriber lookup uses an email address.

Setup and configuration

The dkships/substack-publisher-mcp MCP server requires Node.js 18 or newer and a Substack Publisher API key. The key is generated from a publication's Substack dashboard, although Publisher API availability may vary by publication.

The repository setup flow is to clone the project, install its npm dependencies, and run its build script. The resulting MCP process is configured as a local stdio server using Node.js and the built dist/index.js file. Add the server definition to the MCP client's configuration, place the key in the env section, and restart the client because servers load at startup.

For a single publication, use SUBSTACK_API_KEY. For multiple publications, use the SUBSTACK_API_KEY_<NAME> naming pattern, with one key per publication. The configured names are available through list_publications and can be used to select which publication to query. The API key is sent directly in the authorization header; the README specifically notes that it must not be prefixed with Bearer.

The README documents configuration examples for Claude Desktop, Claude Code, and Cursor. It also notes that Claude Code configurations should specify a stdio server type.

Tools and capabilities

• list_publications lists publications configured through environment variables.
• list_posts returns published posts and supports date filters, sorting, type filtering, result limits, and pagination.
• get_post retrieves a post using its required URL slug.
• get_post_stats retrieves engagement information for a post using its required URL slug.
• get_subscriber_counts returns daily subscriber counts by type for a requested date range.
• get_subscriber looks up a subscriber using a required email address.

The server is suited to questions such as comparing recent post performance, reviewing subscriber growth over a period, finding a post by slug, or checking whether a subscriber record exists. It does not expose write operations in the documented tool list.

Limitations and notes

A valid Publisher API key is required, and the publication must have access to that API. The project documentation points to Substack's Publisher API documentation for API details and rate limits. If no keys are configured, the server reports that condition; invalid keys produce an unauthorized error.

The server runs from the built dist/ directory, so rebuilding after cloning is necessary. A client must be restarted after its MCP configuration changes. Node.js must be installed and available on the system path. The repository is released under the MIT license.