substack-article-mcp

MCP server for Substack — read articles, comments, feed, and subscriptions from Cursor, Claude Desktop, Claude Code, or any MCP client. Public content works without authentication; log in for premium/paywalled articles and personalized features.

Quick Start

Choose your AI client:

Cursor

One command — logs in and configures Cursor automatically:

npx -y substack-article-mcp install --cursor

Restart Cursor after installation.

Claude Code

One command — logs in and adds the MCP globally:

npx -y substack-article-mcp install --claude-code

Claude Desktop

Download the .mcpb extension from the Releases page and double-click to install.

Optional: After installing, go to Extensions > Substack Articles > Settings and paste your Substack cookie to unlock paid articles, subscriptions, and your feed. Leave it empty for public-only access.

Use it

Ask from chat — the app starts the server automatically:

• "List recent articles from platformer" (public, no auth needed)
• "Get the full content of article 184929446" (works with numeric IDs)
• "Show me the comments on this article"
• "Search platformer articles for 'antitrust'"
• "What newsletters do I subscribe to?" (requires auth)
• "Show me my reader feed" (requires auth)

Authentication

Authentication is optional. Public tools (list_articles, get_article, search_articles, get_comments) work without any credentials as long as you specify a subdomain.

Log in to unlock:

• Full paid/premium article content
• list_subscriptions — see all newsletters you follow
• get_feed — your personalized reader feed
• get_inbox — chronological inbox from all subscriptions
• Auto-detected default subdomain (so you don't need to specify one)

How auth works

The server checks for credentials in this priority order:

1. SUBSTACK_COOKIE environment variable — used by Claude Desktop's .mcpb extension (set automatically from the optional cookie field in settings)
2. ~/.substack-article-mcp/auth.json — saved by the login or install command
3. No auth — public content only

Refreshing credentials

Substack cookies expire every few weeks. When tools start returning auth errors:

• Cursor / Claude Code: Run npx -y substack-article-mcp login in your terminal
• Claude Desktop: Go to Extensions > Substack Articles > Settings and paste a fresh cookie

Getting your cookie manually

1. Open substack.com in Chrome and log in
2. DevTools (F12) → Application → Cookies → substack.com
3. Copy the value of substack.sid (and substack.lli for paid articles)
4. Use as: substack.sid=YOUR_VALUE; substack.lli=YOUR_LLI_VALUE

CLI Commands

| Command | Description | |---------|-------------| | npx -y substack-article-mcp install --cursor | Log in + add MCP to Cursor | | npx -y substack-article-mcp install --claude-code | Log in + add MCP to Claude Code | | npx -y substack-article-mcp login | Refresh credentials (Chrome login flow) | | npx -y substack-article-mcp login --manual '<cookie>' | Paste cookies directly | | npx -y substack-article-mcp login --check | Check auth status and cookie age | | npx -y substack-article-mcp --help | Show help | | npx -y substack-article-mcp --version | Show version |

Do not run npx -y substack-article-mcp with no arguments in your terminal. That starts the MCP stdio server and your terminal will appear stuck. Your AI client starts it automatically.

MCP Tools

| Tool | Auth Required | Description | |------|:---:|-------------| | substack_auth_status | No | Check auth status, cookie age, and get refresh guidance | | list_articles | No* | List published articles with metadata and engagement stats | | get_article | No* | Full article as markdown. Accepts slug or numeric post ID | | search_articles | No* | Search articles by keyword | | get_comments | No* | Full comment tree with replies and reactions | | list_subscriptions | Yes | All newsletters you subscribe to (paid, comped, free) | | get_feed | Yes | Personalized reader feed from subscribed newsletters | | get_inbox | Yes | Chronological inbox with pagination |

* Requires a subdomain parameter if not authenticated. Auth is needed for paid/premium content.

All content tools accept an optional subdomain parameter to read any newsletter (e.g., subdomain: "platformer").

get_article and get_comments also accept numeric post IDs (e.g., 184929446). When using an ID, the publication is auto-detected.

Privacy & Security

• The server runs entirely on your local machine as a subprocess of your AI client
• No cloud hosting, no intermediary servers
• Your credentials never leave your computer
• The login command uses a dedicated Chrome profile in ~/.substack-article-mcp/chrome-profile/ — completely separate from your regular Chrome

Requirements

• Node.js 18+
• Google Chrome (for the login / install commands only — not needed for Claude Desktop)

Disclaimer

Uses Substack's internal APIs. Use for personal/experimental purposes. Not affiliated with Substack.

License

MIT