# 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