substack_mcp

# Substack MCP Server for Claude Code A powerful Model Context Protocol (MCP) server that gives Claude Code deep, structured access to Substack publications with real-time content analysis. ## Why Use This? ### 🎯 **Precision Research** - Real-time access to specific Substack publications - Comprehensive publication intelligence - posts, notes, author profiles - Structured data vs. scattered web search results ### 📊 **Built-In Analytics** - Sentiment analysis (VADER-based emotional tone detection) - Readability metrics (Flesch Reading Ease, Kincaid Grade Level) - Keyword extraction (TF-IDF with stopword filtering) - Publishing patterns and content trends ### ⚡ **Live Data** - Fresh content as it's published - No AI knowledge cutoff limitations - Direct access to RSS feeds and public content > ⚠️ **Ethical Use**: Respects Substack's Terms of Service with built-in throttling (1-second delays) for responsible crawling. ## TL;DR - Get Started in 30 Seconds ```bash # 1. Clone and enter the directory git clone https://github.com/yourusername/substack_mcp.git cd substack_mcp # 2. Open Claude Code in this directory # 3. Ask: "Install this MCP server" # 4. Use it: "Get the latest posts from platformer" ``` That's it! Claude Code handles everything else. ## Quick Start with Claude Code ### Option 1: Automatic Installation (Recommended) If you're already in the project directory in Claude Code: 1. **Simply ask Claude Code to set it up:** ``` "Install this MCP server for me" ``` Claude Code will: - Create the virtual environment - Install dependencies - Configure the MCP server automatically - Add it to your MCP configuration 2. **Verify it's installed:** ``` /mcp ``` You should see `substack` (or `substack-mcp`) in the list of available MCP servers. 3. **Start using it:** ``` "Get the latest posts from platformer" "Analyze sentiment for techtiff's recent posts" "Show me publishing patterns for stratechery" ``` ### Option 2: Manual Installation ```bash # Clone the repository (if not already) git clone https://github.com/yourusername/substack_mcp.git cd substack_mcp # Let Claude Code handle the rest, or manually: python3 -m venv .venv source .venv/bin/activate pip install -e . # Then ask Claude Code to: # "Add this MCP server to my configuration" ``` ### Using with Claude Desktop (Alternative) If you want to use with Claude Desktop instead of Claude Code: **Location:** - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Configuration:** ```json { "mcpServers": { "substack": { "command": "/absolute/path/to/substack_mcp/run_mcp_with_venv.sh", "args": [] } } } ``` Then restart Claude Desktop. ## How to Use with Claude Code Once installed, simply talk to Claude Code naturally. The MCP tools work automatically in the background. ### Example Conversations **Research a publication:** ``` You: "Analyze the latest 10 posts from stratechery" Claude Code will: - Use get_posts to fetch the posts - Use analyze_post on each one - Summarize themes, sentiment, and readability patterns ``` **Compare publications:** ``` You: "Compare the writing complexity between platformer and techtiff" Claude Code will: - Fetch posts from both publications - Run readability analysis - Present comparative insights ``` **Deep content analysis:** ``` You: "Get the full content and sentiment analysis for this post: https://techtiff.substack.com/p/sonnet-4-5-release" Claude Code will: - Use get_post_content to fetch the full article - Use analyze_post for sentiment and readability - Provide detailed insights ``` **Track publishing patterns:** ``` You: "What's the publishing cadence for littlehakr?" Claude Code will: - Use crawl_publication with analytics - Calculate average days between posts - Show publishing trends ``` ### Natural Language > Tool Names You don't need to know the tool names. Just ask naturally: - ❌ "Use get_posts with handle=platformer and limit=5" - ✅ "Show me the latest 5 posts from platformer" Claude Code automatically: - Selects the right MCP tools - Extracts parameters from your request - Combines multiple tools when needed - Presents results in a readable format ### Checking MCP Status Use the `/mcp` command anytime to: - List all installed MCP servers - Check if Substack MCP is available - See what other MCP tools you have ``` /mcp ``` Output will show: ``` Available MCP servers: - substack (13 tools available) - search - get_posts - get_all_posts - search_substack - get_content - discover_publications - analyze_trends - get_post_content - analyze_post - get_author_profile - get_notes - search_notes - crawl_publication ``` ## Available Tools ### 🔍 **Content Discovery** #### `get_posts` Fetch recent posts from a Substack publication. ``` Parameters: - handle (required): Publication handle (e.g., 'platformer') - limit (optional): Number of posts (1-50, default: 10) ``` #### `get_all_posts` Get ALL posts from a publication's archive (not limited to recent posts). ``` Parameters: - handle (required): Publication handle (e.g., 'platformer') - before_date (optional): ISO date string (e.g., '2025-08-20') - only posts before this date - after_date (optional): ISO date string (e.g., '2025-01-01') - only posts after this date - limit (optional): Maximum number of posts to return Features: - Uses pagination to fetch complete archive - Supports date range filtering - Early termination when date filters are satisfied - Cached with TTL for performance ``` #### `get_post_content` Get full content of a specific Substack post. ``` Parameters: - url (required): Full URL to the Substack post ``` #### `search` Basic search for content across publications. ``` Parameters: - query (required): Search terms - handle (optional): Specific publication to search ``` #### `search_substack` Intelligently search for content with auto-discovery of relevant publications. ``` Parameters: - query (required): Natural language search query (topics, keywords, author names, or themes) Examples: 'AI regulation', 'crypto DeFi', 'Ben Thompson tech analysis' - publication_hint (optional): Hint about publication to focus on Features: - Auto-discovers relevant publications based on query - Supports natural language queries - Smart content matching (phrase and multi-term matching) - Searches across multiple publications simultaneously - Returns top 8 most relevant results ``` #### `get_content` Smart content retrieval that works with URLs, publication names, or handles. ``` Parameters: - target (required): What to fetch - URL, publication name, or handle Examples: 'https://stratechery.com/post', 'platformer', 'Ben Thompson latest' - analysis_type (optional): 'full' (content + analytics), 'summary' (recent posts), 'profile' (author info) Features: - Handles multiple input formats (URLs, names, handles) - Automatic publication hint resolution - Full analytics when requested - Flexible output based on analysis type ``` #### `discover_publications` Discover Substack publications by topic, industry, or theme. ``` Parameters: - topic (required): Topic or industry to explore Examples: 'tech', 'finance', 'AI', 'crypto', 'politics', 'business strategy' Returns: - Curated list of publications for the topic - Publication descriptions - Latest posts from each publication - Direct links to publications ``` #### `analyze_trends` Analyze content trends, publishing patterns, and themes. ``` Parameters: - focus (required): Publication name, author, or topic to analyze Examples: 'stratechery publishing patterns', 'AI content trends', 'Casey Newton' - analysis_depth (optional): 'quick' (recent), 'deep' (comprehensive), 'comparative' (multiple sources) Returns: - Publishing frequency and patterns - Common themes and topics - Recent posts overview - Keyword analysis - Cross-publication comparison (when applicable) ``` ### 📊 **Analytics & Intelligence** #### `analyze_post` Analyze sentiment and readability of a post. ``` Parameters: - url (required): Full URL to the Substack post Returns: - Sentiment scores (positive, negative, neutral, compound) - Readability metrics (Flesch Reading Ease, grade level) - Keyword extraction - Word count and structure analysis ``` #### `get_author_profile` Get author and publication information. ``` Parameters: - handle (required): Substack publication handle Returns: - Author bio and profile - Publication metadata - Social links ``` #### `get_notes` Get recent Substack notes from a publication. ``` Parameters: - handle (required): Publication handle - limit (optional): Number of notes (1-50, default: 10) Returns: - List of notes with content, author, published date, and URL ``` #### `search_notes` Search for notes containing specific text. ``` Parameters: - handle (required): Publication handle - query (required): Search terms to find in notes - limit (optional): Max results (1-50, default: 20) Returns: - Filtered list of notes matching the search query ``` #### `crawl_publication` Comprehensive publication crawl with analytics. ``` Parameters: - handle (required): Publication handle - post_limit (optional): Max posts (1-25, default: 5) - notes_limit (optional): Max notes (0-50, default: 10) - analyze (optional): Perform analytics (default: true) Returns: - Complete publication overview - Author profile - Recent posts with analytics - Recent notes - Publishing patterns ``` ## Common Use Cases ### Content Strategy Research ``` "What topics is stratechery covering this month?" "How often does platformer publish?" "Compare the keyword focus between two tech newsletters" ``` ### Writing Analysis ``` "Is techtiff's content getting easier or harder to read over time?" "What's the average grade level for this publication?" "Show me sentiment trends in recent posts" ``` ### Competitive Intelligence ``` "Compare publishing frequency across 3 tech newsletters" "Which newsletter has the most positive sentiment?" "Identify content gaps between competing publications" ``` ### Author Research ``` "Give me a profile of the stratechery author" "What's their publishing pattern?" "Show me their most recent posts with analytics" ``` ### Deep Content Dives ``` "Analyze this specific post for readability and sentiment: [URL]" "Extract key themes from the last 20 posts" "Show me how their writing style has evolved" ``` ### Quick Checks ``` "Latest posts from platformer" "What did techtiff write about this week?" "Get notes from this publication" ``` ### Notes Research ``` "Show me recent notes from techtiff" "Search techtiff's notes for mentions of 'Claude'" "Find notes about AI automation from this author" "What topics is this writer covering in their notes?" ``` ### Archive Research ``` "Get all posts from platformer published in 2024" "Show me techtiff's posts after January 1, 2025" "Fetch the complete archive from stratechery before August 2025" "Get all historical posts from this publication with no limit" ``` ### Intelligent Search & Discovery ``` "Search for content about AI regulation" "Find posts discussing crypto DeFi across tech newsletters" "What's Ben Thompson writing about machine learning?" "Discover publications focused on AI and show me their latest content" "What tech publications cover remote work trends?" ``` ### Advanced Analytics ``` "Analyze publishing patterns for stratechery" "Show me content trends about AI across multiple publications" "Compare writing frequency between platformer and techtiff" "What are the common themes in recent tech newsletter content?" ``` ## Analytics Capabilities ### Content Metrics - **Sentiment Analysis**: Positive, negative, neutral, and compound scores - **Readability**: Flesch Reading Ease (0-100 scale) - **Grade Level**: Flesch-Kincaid Grade Level - **Lexical Diversity**: Vocabulary richness metrics - **Structure**: Word count, sentence count, average sentence length ### Publication Intelligence - **Publishing Cadence**: Average days between posts - **Content Trends**: Topic evolution over time - **Keyword Analysis**: TF-IDF-based keyword extraction - **Author Patterns**: Writing style consistency ## Project Structure ``` substack_mcp/ ├── src/substack_mcp/ │ ├── client.py # HTTP client with rate limiting │ ├── models.py # Pydantic data models │ ├── parsers.py # RSS/HTML parsing │ ├── analysis.py # Text analytics │ ├── cache.py # TTL-based caching │ ├── server.py # MCP server implementation │ └── settings.py # Configuration ├── tests/ # Test suite ├── scripts/ # Utility scripts └── run_mcp_with_venv.sh # Wrapper script ``` ## Configuration Optional environment variables: ```bash # Request throttling (seconds between requests) export SUBSTACK_MCP_THROTTLE=1.0 # Cache time-to-live (seconds) export SUBSTACK_MCP_CACHE_TTL=900 # Publication to warm cache on startup export SUBSTACK_MCP_WARM_PUBLICATION=platformer ``` ## Troubleshooting ### MCP Server Not Showing Up **Check with `/mcp` command:** ``` /mcp ``` If you don't see `substack` in the list: 1. **Ask Claude Code to help:** ``` "The substack MCP server isn't showing up in /mcp. Can you help install it?" ``` 2. **Verify installation:** ```bash cd /path/to/substack_mcp ls run_mcp_with_venv.sh # Should exist source .venv/bin/activate pip list | grep mcp # Should show mcp==1.10.0 ``` 3. **Check Python version:** ```bash python3 --version # Should be 3.10 or higher ``` ### Tools Not Working If Claude Code says tools aren't available: 1. **Reinstall dependencies:** ``` "Can you reinstall the dependencies for this MCP server?" ``` 2. **Check for errors:** ```bash ./run_mcp_with_venv.sh # Should start without errors (Ctrl+C to exit) ``` ### Claude Desktop Not Connecting If using Claude Desktop instead of Claude Code: 1. Ensure `claude_desktop_config.json` has correct absolute path 2. Make wrapper script executable: `chmod +x run_mcp_with_venv.sh` 3. Restart Claude Desktop after config changes ### Rate Limiting Issues If you see HTTP 429 errors or timeouts: - The server has built-in 1-second throttling - Reduce the number of posts you're analyzing at once - Try again after a brief pause ## Technical Notes ### MCP SDK Version This server uses MCP SDK v1.10.0 (locked) with a workaround for a CallToolResult serialization bug in later versions. The implementation uses custom `create_text_result()` functions that return plain dictionaries. ### Rate Limiting Built-in 1-second throttle between requests to respect Substack's infrastructure. Uses TTL-based in-memory cache (15 minutes default). ### Public Content Only This tool accesses only public Substack content. No authentication or paywalled content access. ## Getting Help ### Using Claude Code The best way to get help is to ask Claude Code directly: ``` "I'm having trouble with the substack MCP server. Can you help diagnose?" "How do I use this MCP server to analyze multiple publications?" ``` ### Documentation - **[CLAUDE.md](CLAUDE.md)** - Developer documentation for working on this project - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines - **GitHub Issues** - Report bugs or request features ### Quick Checks ```bash # Verify installation /mcp # Test manually cd substack_mcp && ./run_mcp_with_venv.sh # Check Python and dependencies python3 --version source .venv/bin/activate && pip list ``` ## Contributing Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Roadmap - [ ] Persistent storage (SQLite) for cached content - [ ] Background worker for scheduled crawls - [ ] Advanced summarization and topic modeling - [ ] Support for authenticated content (pending ToS review) --- **Built for [Claude Code](https://claude.com/claude-code)** - The official Anthropic CLI for Claude. Made with ❤️ for Substack researchers, content strategists, and AI enthusiasts.