Substack MCP

🚀 Substack MCP Server

A server implementing the Model Context Protocol (MCP) to integrate the Substack API into Claude and other AI assistants.

🚀 Quick Start

This project implements a Model Context Protocol (MCP) server, enabling AI assistants like Claude to interact with Substack newsletters, articles, and authors through a unified interface. It is based on the Substack API library and provides its functionality via MCP.

With this MCP server, Claude can:

• Retrieve newsletter articles, podcasts, and recommendations.
• Obtain article content and metadata.
• Search for articles within newsletters.
• Get user profile information and subscriptions.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• Claude Desktop (for testing).

Setup

1. Clone this repository:

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

2. Initialize 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
   

3. Install dependencies:

   uv add "mcp[cli]" substack-api
   

💻 Usage Examples

Basic Usage

Run the Server

Run the MCP server:

python substack_mcp.py

Configure Claude Desktop

1. Open the configuration file for Claude Desktop:

   • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add your server configuration:

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

3. Restart Claude Desktop.

Example Queries

After configuration, you can ask Claude questions like:

• Get the list of articles in a specific newsletter.
• View detailed information and content of an article.
• Search for a specific topic or keyword.
• List all subscriptions of a user.
• Get the latest updates of a subscription.

📚 Documentation

Project Structure

substack-mcp/
├── README.md          # Project documentation
├── substack_mcp.py    # Main MCP server implementation
└── requirements.txt   # Dependency list

⚠️ Important Note

• All API requests require a valid authentication token.
• Ensure the server runs in a secure network environment.
• Regularly update the API token to enhance security.

By following the above steps, you can easily integrate Substack content into any AI assistant that supports the MCP protocol, expanding its functionality and application scenarios.