# Substack Reader MCP Server
An MCP (Model Context Protocol) server for reading your Substack subscriptions from Claude Code.
## Installation
```bash
# 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
```bash
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
```bash
make install
```
### 2. Export Substack Cookies
1. Install [Cookie-Editor](https://cookie-editor.com/) browser extension
2. Log into [substack.com](https://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`:
```json
{
"username": "your-substack-username"
}
```
Your username is from your Substack profile URL (e.g., `substack.com/@username`).
### 4. Configure Claude Code
Run:
```bash
make configure
```
Or manually add to `~/.claude/settings.json`:
```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
```bash
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
