README - Substack MCP by greg-swiftomatic

Substack MCP

An MCP (Model Context Protocol) server for Substack API integration with Claude and other AI assistants.

Overview

This project implements a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Substack newsletters, posts, and authors through a standardized interface. It leverages the Substack API library and makes its functionality available through MCP.

With this MCP server, Claude can:

Retrieve newsletter posts, podcasts, and recommendations
Get post content and metadata
Search for posts within newsletters
Get user profile information and subscriptions

Installation

Prerequisites

Python 3.10 or higher
Claude for Desktop (for testing)

Setup

Clone this repository:

git clone https://github.com/Greg-Swiftomatic/substack-mcp.git
cd substack-mcp

Set up a virtual environment using uv:

curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv if not already installed
uv init .
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
uv add "mcp[cli]" substack-api
```

Usage

Running the Server

Run the MCP server:

python substack_mcp.py

Configuring Claude for Desktop

Open Claude for Desktop's configuration file:
- macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your server configuration:

{
    "mcpServers": {
        "substack": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/substack-mcp",
                "run",
                "substack_mcp.py"
            ]
        }
    }
}

Restart Claude for Desktop.

Example Queries

Once configured, you can ask Claude questions like:

"Show me recent posts from https://stratechery.com/"
"What's the content of this post: https://stratechery.com/2023/the-ai-unbundling/"
"Search for 'AI' on https://stratechery.com/"
"Who are the authors of https://stratechery.com/?"

Available Tools

The server provides the following MCP tools:

Tool	Description
`get_newsletter_posts`	Retrieves recent posts from a Substack newsletter
`get_post_content`	Gets the full content of a specific Substack post
`search_newsletter`	Searches for posts within a newsletter
`get_author_info`	Gets information about a Substack author
`get_newsletter_recommendations`	Gets recommended newsletters for a Substack publication
`get_newsletter_authors`	Gets authors of a Substack newsletter

Project Structure

substack_mcp.py - The main MCP server implementation
examples/ - Example queries and responses
docker/ - Docker configuration for containerized deployment

Development

To contribute to this project:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

If you encounter issues:

Check Claude's logs for errors:

# macOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

Verify your server builds and runs without errors:
```
python substack_mcp.py
```
Make sure your claude_desktop_config.json file has the correct paths and syntax.
Try restarting Claude for Desktop completely.

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Substack API - The underlying library for Substack interactions
Model Context Protocol - Anthropic's protocol for standardized LLM integrations