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.

🛠️ Tools

Related MCP server: club-mcp

⚙️ 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   # run the integration test suite against live Substack endpoints

The test suite makes real requests against live publications, so it needs a valid SUBSTACK_SESSION_TOKEN and is subject to Substack's rate limits.

📄 License

MIT