Substack Reader MCP Server

An MCP (Model Context Protocol) server for reading your Substack subscriptions from Claude Code.

Installation

# Clone the repo
git clone git@github.com:Kealu-Inc/substack-reader-mcp.git ~/.claude/mcp-servers/substack-reader

# Run setup
cd ~/.claude/mcp-servers/substack-reader
make setup

Features

list_subscriptions - List all newsletters you subscribe to
get_feed - Get recent posts from all your subscriptions
get_recent_posts - Get posts from a specific newsletter
read_post - Read full content of any post
search_newsletter - Search within a newsletter

Quick Start

cd ~/.claude/mcp-servers/substack-reader
make setup

This will:

Install Python dependencies
Guide you through exporting browser cookies
Configure your Substack username
Add the MCP server to Claude Code settings
Test the connection

Manual Setup

1. Install Dependencies

make install

2. Export Substack Cookies

Install Cookie-Editor browser extension
Log into substack.com
Click Cookie-Editor → Export → Export as JSON
Save to ~/.config/substack-reader/cookies.json

3. Configure Username

Create ~/.config/substack-reader/config.json:

{
  "username": "your-substack-username"
}

Your username is from your Substack profile URL (e.g., substack.com/@username).

4. Configure Claude Code

Run:

make configure

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "substack-reader": {
      "command": "python3",
      "args": ["/path/to/substack-reader/server.py"],
      "env": {
        "SUBSTACK_USERNAME": "your-username",
        "SUBSTACK_COOKIES_PATH": "/path/to/cookies.json"
      }
    }
  }
}

5. Restart Claude Code

The MCP server will load on restart.

Usage Examples

After setup, ask Claude:

"List my Substack subscriptions"
"Get my subscription feed"
"Get recent posts from The Pragmatic Engineer"
"Read the latest post about system design"
"Search for 'microservices' in Engineering Leadership"

Testing

make test

Troubleshooting

"No subscriptions found"

Verify your username is correct
Check cookies are exported properly (should include substack.sid)

"Authentication error"

Re-export cookies from browser (they may have expired)
Ensure you're logged into Substack when exporting

MCP server not loading

Check ~/.claude/settings.json syntax is valid JSON
Verify the server path is correct
Restart Claude Code completely

Files

~/.claude/mcp-servers/substack-reader/
├── server.py          # Main MCP server
├── setup.py           # Interactive setup wizard
├── Makefile           # Setup automation
├── scripts/
│   ├── configure_claude.py
│   └── test_server.py
└── README.md

~/.config/substack-reader/
├── config.json        # Username configuration
└── cookies.json       # Browser cookies (keep private!)

Security

Never commit cookies.json - it contains your session
Cookies expire periodically - re-export when auth fails
The server only reads content you have access to

License

MIT