Substack MCP Server

🚀 Substack MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to interact with Substack newsletters, articles, and user profiles.

🚀 Quick Start

This project transforms the Substack API library into an Anthropic MCP server, allowing Claude to:

• Retrieve newsletter articles, podcasts, and recommended content.
• Obtain user profile information and subscription details.
• Fetch article content and metadata.
• Search for articles within specific newsletters.
• Conduct simultaneous searches across multiple Substack newsletters.
• Discover popular Substack newsletters by category.

📦 Installation

Prerequisites

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

Installation Steps

# Clone the repository
git clone https://github.com/Greg-Swiftomatic/substack-mcp-server.git
cd substack-mcp-server

# Set up a virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Alternatively, use uv:

# Use uv for faster installation
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

💻 Usage Examples

Basic Usage

Run the Server

python substack_mcp.py

Connect with Claude Desktop

1. Open your Claude Desktop configuration file:

   # MacOS
   open ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   type %APPDATA%\Claude\mcp*.log
   

2. Add the following content to claude-config.json:

   {
     "context_providers": {
       "substack_mcp": {
         "type": "custom",
         "class": "SubstackMCPProvider",
         "args": {
           "server_url": "http://localhost:1234"
         }
       }
     }
   }
   

Advanced Usage

Get Newsletter Posts (get_newsletter_posts)

• Parameters: newsletter_id (required)
• Return Value: A dictionary containing a list of articles and metadata.
• Example Response:

  {
    "posts": [
      {
        "id": "123",
        "title": "Latest Tech News",
        "content": "Explore future tech trends..."
      }
    ],
    "metadata": {
      "total_count": 10,
      "page": 1
    }
  }
  

Get User Profile (get_user_profile)

• Parameters: None
• Return Value: A dictionary containing user details.
• Example Response:

  {
    "user_id": "456",
    "username": "tech_guru",
    "subscriber_count": 10000
  }
  

Search Posts (search_posts)

• Parameters: query (required), newsletter_id (optional)
• Return Value: A list of search results and metadata.
• Example Response:

  {
    "results": [
      {
        "id": "789",
        "title": "The Future of AI",
        "contentSnippet": "...Applications and development of artificial intelligence..."
      }
    ],
    "metadata": {
      "total_count": 20,
      "page": 1
    }
  }
  

📚 Documentation

Development and Contribution

Create a Feature Branch

# Clone the repository
git clone https://github.com/Greg-Swiftomatic/substack-mcp-server.git

# Create a new feature branch
git checkout -b feature/amazing-feature

# Commit changes
git commit -m 'Added an amazing feature'

# Push to the remote repository
git push origin feature/amazing-feature

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

👏 Acknowledgments

• NHagar/substack_api - The original Substack API library.
• Model Context Protocol - Anthropic's MCP specification.