substack-publisher-mcp

MCP server for Substack's official Publisher API

Note: This is an unofficial, community-developed tool and is not affiliated with, endorsed by, or supported by Substack, Inc.

The first MCP server for Substack's official Publisher API. Query post analytics, subscriber counts, and publication data directly from Claude, Cursor, or any MCP client.

Why this server?

Tools

All tools except list_publications accept an optional publication parameter when multiple publications are configured.

Example responses

[
  {
    "date": "2025-01-15",
    "total_email_subscribers": 25000,
    "paid_subscribers": 500,
    "free_trial_subscribers": 10,
    "comp_subscribers": 50,
    "gift_subscribers": 15,
    "lifetime_subscribers": 0,
    "founding_subscribers": 25
  }
]

{
  "clicks": 320,
  "opens": 5400,
  "post_id": 12345678,
  "recipients": 10000,
  "views": 6100,
  "new_free_subscriptions": 80,
  "new_paid_subscriptions": 5,
  "estimated_revenue_increase": 400
}

{
  "posts": [
    {
      "title": "My Latest Post",
      "audience": "only_paid",
      "subtitle": "A deep dive into the topic",
      "postDate": "2025-01-15T12:00:00.000Z",
      "urlSlug": "my-latest-post",
      "coverImage": "https://substackcdn.com/image/..."
    }
  ],
  "next": "abc123cursor"
}

Multiple publications

If you manage multiple Substack publications, configure a separate API key for each using the SUBSTACK_API_KEY_<NAME> pattern:

{
  "mcpServers": {
    "substack": {
      "command": "node",
      "args": ["/path/to/substack-publisher-mcp/dist/index.js"],
      "env": {
        "SUBSTACK_API_KEY_MAIN": "your-main-blog-key",
        "SUBSTACK_API_KEY_TECH": "your-tech-newsletter-key",
        "SUBSTACK_API_KEY_COMPANY": "your-company-updates-key"
      }
    }
  }
}

Then specify which publication to query:

"Show me subscriber counts for main" "List recent posts from the tech publication"

Use list_publications to see all configured publication names.

API Reference

This server wraps the Substack Publisher API. See Substack's documentation for details on available data and rate limits.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.

Substack is a trademark of Substack, Inc. This project is not affiliated with Substack, Inc. Use of the Substack name is for descriptive purposes only.

Prerequisites

• Node.js 18+ — check with node --version, install from nodejs.org if missing
• Substack Publisher API key — generated from your publication's Substack dashboard. If you don't see a Publisher API option there, it may not be enabled for your publication yet; see the Publisher API docs for availability.

Quick Start

1. Install

git clone https://github.com/dkships/substack-publisher-mcp.git
cd substack-publisher-mcp
npm install && npm run build

2. Configure your MCP client

Add to your client's MCP config file (create the file if it doesn't exist):

{
  "mcpServers": {
    "substack": {
      "command": "node",
      "args": ["/path/to/substack-publisher-mcp/dist/index.js"],
      "env": {
        "SUBSTACK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code users: Add "type": "stdio" to the server config.

Restart your MCP client after editing the config — servers load at startup.

3. Start using it

Ask Claude (or your MCP client):

• "Which Substack publications do I have configured?"
• "Show me my posts from the last month"
• "Pull up my post with the slug my-latest-post"
• "How many opens and clicks did my latest post get?"
• "What are my subscriber counts for the last 30 days?"
• "Look up subscriber jane@example.com"

Installing through an AI agent or registry? See llms-install.md for a condensed, machine-readable setup guide.

Troubleshooting