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
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:
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 LICENSE file for details.
Acknowledgments