dkships/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.
An MCP server for Substack's official Publisher API. Search and read posts, pull post analytics and subscriber counts, and look up subscribers from Claude, Cursor, or any MCP client. All tools are read-only.
Why this server?
| | substack-publisher-mcp | Other Substack MCP servers |
|---|---|---|
| **API** | Official Publisher API | Unofficial internal API |
| **Auth** | API key (stable) | Browser cookies (fragile) |
| **Stability** | Official, documented API | Breaks when Substack changes internals |
| **Multi-publication** | Built-in support | Not available |
Prerequisites
- **Node.js 22+.** Check with node --version; install from nodejs.org if missing.
- **Substack Publisher API key.** Generate one 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
2. Configure your MCP client
Add to your client's MCP config file (create the file if it doesn't exist):
| Client | Config file |
|--------|-------------|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Claude Code | .mcp.json in your project directory |
| Cursor | .cursor/mcp.json |
> **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"*
- *"Find my posts about pricing"*
- *"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.
Tools
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| list_publications | List configured publications | None |
| list_posts | List published posts | startDate, endDate, sortBy, type, maxResults, next |
| search_posts | Full-text search across published posts | query (required), maxResults (1-100) |
| get_post | Get a post and its body by URL slug | urlSlug (required), bodyFormat |
| get_post_stats | Get engagement stats for a post | urlSlug (required) |
| get_subscriber_counts | Get daily subscriber counts by type | startDate, endDate |
| get_subscriber | Look up a subscriber by email | email (required) |
All tools except list_publications accept an optional publication parameter when multiple publications are configured.
get_post returns the post body as Markdown by default. Substack sends it as a JSON-encoded ProseMirror document, typically about twice the size. Pass bodyFormat: "prosemirror" for the raw document or "none" for metadata only.