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:

1. Install Python dependencies
2. Guide you through exporting browser cookies
3. Configure your Substack username
4. Add the MCP server to Claude Code settings
5. Test the connection

Manual Setup

1. Install Dependencies

make install

2. Export Substack Cookies

1. Install Cookie-Editor browser extension
2. Log into substack.com
3. Click Cookie-Editor → Export → Export as JSON
4. 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