substack-mcp 📰

An MCP server for reading Substack — publications, posts, comments, author profiles, recommendations, and your Notes feed — using your own reader session, no official API required.

For use with Claude, Codex, and other MCP-compatible coding agents.

It's read-only 🔒: nothing it does can post, like, comment, or change your account state. The session cookie is only ever sent to Substack hosts you're actually subscribed to, and tool output is wrapped in a delimited block marking it as untrusted third-party content (post bodies and comments are written by other people, not you) — both defenses against prompt injection carried in what you read.

🛠️ Tools

| Tool | Description | |---|---| | list_published_posts | List recent posts from a publication | | get_post | Get a post's full content by domain + slug (works on paywalled posts if you're a paid subscriber) | | get_post_by_url | Get a post's full content from any post URL, including generic substack.com/@handle/p-<id> links | | search_posts | Search posts within a publication | | search_all_subscriptions | Search across every publication you're subscribed to or follow | | list_subscriptions | List your subscriptions (free and paid) | | get_inbox | New posts across every publication you read, newest first, with read/unread state. Optional tag filter | | get_post_comments | Get a post's comments, with nested replies, by domain + slug | | get_post_comments_by_url | Same, from any post URL | | get_author_profile | Get an author's public profile (bio, social links, publications they write for) | | get_recommendations | List publications a given publication recommends to its readers | | get_notes_feed | List recent items from your Notes home feed | | tag_publication | Tag a publication by topic (e.g. financial-research) for use with search_all_subscriptions/get_inbox's tag filter. Empty array untags | | list_tags | List every tag you've set and which publications carry each one |

🏷️ Tagging

Substack doesn't expose a topic or category field for publications — tag_publication is a local layer this server keeps for you, stored at ~/.substack-mcp/tags.json (override with SUBSTACK_MCP_TAGS_FILE). Tag your accounts by whatever grouping you want — e.g. financial-research for the ones covering markets, something else for the rest — then pass tag to search_all_subscriptions or get_inbox to scope to just that group. Nothing here reads or infers a topic from Substack itself; you (or your agent, reading a few recent post titles) decide what a publication is about.

⚙️ How it works

Substack doesn't expose a public API for these reads. Instead, this server replays the same /api/v1/* requests your browser makes when you're logged in, authenticated with your substack.sid session cookie. That means:

• You need an active Substack account and a valid session token.
• The token expires periodically — when requests start failing with an auth error, re-extract it (see below).

⚠️ This is an unofficial library and is not affiliated with or endorsed by Substack. It only accesses content you're already entitled to (your own subscriptions, public posts, and your own account data) and doesn't bypass paywalls or rate limits. Be mindful of Substack's Terms of Use when using it.

🚀 Setup

git clone https://github.com/ryanrodrigues25200525-svg/substack-mcp.git
cd substack-mcp
npm install
npm run build

🔑 Get your session token

1. Log into Substack in your browser.
2. Open DevTools → Application/Storage → Cookies → substack.com.
3. Copy the value of the substack.sid cookie.

🔌 Configure your MCP client

Add to your MCP client's config (e.g. Claude Code's ~/.claude.json, under mcpServers):

{
  "mcpServers": {
    "substack": {
      "command": "node",
      "args": ["/absolute/path/to/substack-mcp/dist/index.js"],
      "env": {
        "SUBSTACK_SESSION_TOKEN": "your_token_here"
      }
    }
  }
}

🚫 Never commit your token. Keep it in your local MCP client config only, not in this repo or in version control.

🧪 Development

npm run build               # compile TypeScript
SUBSTACK_SESSION_TOKEN=xxx npm test   # integration suite against live Substack endpoints
npm run test:trust           # unit tests for the session-cookie trust boundary (stubbed, no token needed)

npm test makes real requests against live publications, so it needs a valid SUBSTACK_SESSION_TOKEN and is subject to Substack's rate limits. npm run test:trust stubs fetch and covers which hosts get the session cookie, path escaping, and the untrusted-content envelope — no network, no token.

📄 License

MIT