A powerful Model Context Protocol (MCP) server that gives Claude Code deep, structured access to Substack publications with real-time content analysis.
- Real-time access to specific Substack publications
- Comprehensive publication intelligence - posts, notes, author profiles
- Structured data vs. scattered web search results
- 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
- 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.
# 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.
If you're already in the project directory in Claude Code:
-
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
-
Verify it's installed:
/mcpYou should see
substack(orsubstack-mcp) in the list of available MCP servers. -
Start using it:
"Get the latest posts from platformer" "Analyze sentiment for techtiff's recent posts" "Show me publishing patterns for stratechery"
# 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"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:
{
"mcpServers": {
"substack": {
"command": "/absolute/path/to/substack_mcp/run_mcp_with_venv.sh",
"args": []
}
}
}Then restart Claude Desktop.
Once installed, simply talk to Claude Code naturally. The MCP tools work automatically in the background.
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
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
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
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 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 full content of a specific Substack post.
Parameters:
- url (required): Full URL to the Substack post
Basic search for content across publications.
Parameters:
- query (required): Search terms
- handle (optional): Specific publication to search
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
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 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 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)
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 and publication information.
Parameters:
- handle (required): Substack publication handle
Returns:
- Author bio and profile
- Publication metadata
- Social links
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 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
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
"What topics is stratechery covering this month?"
"How often does platformer publish?"
"Compare the keyword focus between two tech newsletters"
"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"
"Compare publishing frequency across 3 tech newsletters"
"Which newsletter has the most positive sentiment?"
"Identify content gaps between competing publications"
"Give me a profile of the stratechery author"
"What's their publishing pattern?"
"Show me their most recent posts with analytics"
"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"
"Latest posts from platformer"
"What did techtiff write about this week?"
"Get notes from this publication"
"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?"
"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"
"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?"
"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?"
- 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
- Publishing Cadence: Average days between posts
- Content Trends: Topic evolution over time
- Keyword Analysis: TF-IDF-based keyword extraction
- Author Patterns: Writing style consistency
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
Optional environment variables:
# 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=platformerCheck with /mcp command:
/mcp
If you don't see substack in the list:
-
Ask Claude Code to help:
"The substack MCP server isn't showing up in /mcp. Can you help install it?" -
Verify installation:
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
-
Check Python version:
python3 --version # Should be 3.10 or higher
If Claude Code says tools aren't available:
-
Reinstall dependencies:
"Can you reinstall the dependencies for this MCP server?" -
Check for errors:
./run_mcp_with_venv.sh # Should start without errors (Ctrl+C to exit)
If using Claude Desktop instead of Claude Code:
- Ensure
claude_desktop_config.jsonhas correct absolute path - Make wrapper script executable:
chmod +x run_mcp_with_venv.sh - Restart Claude Desktop after config changes
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
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.
Built-in 1-second throttle between requests to respect Substack's infrastructure. Uses TTL-based in-memory cache (15 minutes default).
This tool accesses only public Substack content. No authentication or paywalled content access.
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?"
- CLAUDE.md - Developer documentation for working on this project
- CONTRIBUTING.md - Contribution guidelines
- GitHub Issues - Report bugs or request features
# Verify installation
/mcp
# Test manually
cd substack_mcp && ./run_mcp_with_venv.sh
# Check Python and dependencies
python3 --version
source .venv/bin/activate && pip listContributions welcome! Please see CONTRIBUTING.md for guidelines.
MIT License - see LICENSE file for details.
- 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 - The official Anthropic CLI for Claude.
Made with ❤️ for Substack researchers, content strategists, and AI enthusiasts.