# 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"

# 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"

{
  "mcpServers": {
    "substack": {
      "command": "/absolute/path/to/substack_mcp/run_mcp_with_venv.sh",
      "args": []
    }
  }
}

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

You: "Compare the writing complexity between platformer and techtiff"

Claude Code will:
- Fetch posts from both publications
- Run readability analysis
- Present comparative insights

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

You: "What's the publishing cadence for littlehakr?"

Claude Code will:
- Use crawl_publication with analytics
- Calculate average days between posts
- Show publishing trends

/mcp

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

Parameters:
- handle (required): Publication handle (e.g., 'platformer')
- limit (optional): Number of posts (1-50, default: 10)

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

Parameters:
- url (required): Full URL to the Substack post

Parameters:
- query (required): Search terms
- handle (optional): Specific publication to search

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

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

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

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)

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

Parameters:
- handle (required): Substack publication handle

Returns:
- Author bio and profile
- Publication metadata
- Social links

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

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

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?"

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

# 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

/mcp

"I'm having trouble with the substack MCP server. Can you help diagnose?"
"How do I use this MCP server to analyze multiple publications?"

# 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