substack-publisher

substack-publisher-mcp exposes the official Substack Publisher API through MCP, allowing clients to query publication data, post analytics, and subscriber information programmatically. The server is designed to be used by MCP clients such as Claude or Cursor, enabling you to fetch lists of publications, retrieve individual post stats, and monitor subscriber activity via a stable, documented API surface. Tools implemented by this MCP server include list_publications to enumerate configured publications, list_posts to fetch posts within a date range, get_post and get_post_stats for per-post data, and get_subscriber_counts or get_subscriber for subscriber insights. You can configure multiple publications by supplying separate API keys per publication, and then specify which publication to query using the publication parameter when you call a tool. To use, start the server via Node.js, ensure your environment variable SUBSTACK_API_KEY is set (or SUBSTACK_API_KEY_<NAME> when using multiple publications), and then invoke the desired tool through your MCP client. When working in Claude Code, you can query texts like “Show me my recent posts” or “What are my subscriber counts for the last 30 days?” to fetch data from the configured Substack publications.

Prerequisites:

• Node.js 18+
• An API key from Substack Publisher API (SUBSTACK_API_KEY)

Installation steps:

1. Clone the repository

git clone https://github.com/dkships/substack-publisher-mcp.git
cd substack-publisher-mcp

2. Install dependencies and build

npm install
npm run build

3. Run the MCP server

# Ensure the dist/index.js path is correct for your environment
# You may also configure environment variables as shown in the example
SUBSTACK_API_KEY=your-api-key-here npm start

4. Configure your MCP client with the server details (see mcp_config below) and point it to the built dist/index.js file.

Tips and common notes:

• If you manage multiple Substack publications, provide separate API keys with environment variables like SUBSTACK_API_KEY_MAIN, SUBSTACK_API_KEY_TECH, etc., and reference the appropriate key per configured publication.
• After cloning, remember to run npm run build because the server runs from the dist/ directory, not src/
• In Claude Code, add type: stdio to the server config as required.
• Ensure SUBSTACK_API_KEY is kept secure and not checked into version control.
• If you encounter Unauthorized errors, double-check that your API key is correct and being sent in the proper header per the Publisher API docs.
• The MCP config uses a single server entry named substack in this example; you can rename it to whatever makes sense for your client configuration.