mcp server

substack-mcp

FastMCP 3.1+ Model Context Protocol (MCP) server & SOTA React webapp dashboard for Substack newsletter feeds, draft staging, local LLM assistance, and analytics.

sandraschi/substack-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sandraschi-substack-mcp": {
      "command": "uvx",
      "args": [
        "substack-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 27, 2026

📰 Substack MCP (`substack-mcp`)

FastMCP 3.1+ Model Context Protocol (MCP) server & SOTA React webapp dashboard for Substack newsletters.

Quick Start • What is Substack? • Dual Capabilities • Onboarding • Just Commands • Documentation

🧠 What is Substack?

Substack is an independent publishing platform and creator network founded in 2017. It allows writers, journalists, researchers, podcasters, and thinkers to publish long-form newsletters directly to their readers' email inboxes and the web.

+-----------------------------------------------------------------------------------+
|                              Substack Publication                                 |
+----------------------------------------+------------------------------------------+
                                         |
     +-------------------+---------------+---------------+--------------------+
     |                   |                               |                    |
     v                   v                               v                    v
+---------+     +------------------+           +-------------------+    +-------------------+
|  Posts  |     | Substack Notes   |           |  Substack Chat    |    | Subscriber Tiers  |
| (Email  |     | (Short-form      |           | (Community        |    | (Free, Monthly,   |
| + Web)  |     |  Social Feed)    |           |  Messaging)       |    |  Annual, Founder) |
+---------+     +------------------+           +-------------------+    +-------------------+

📖 Want a deep dive? Read our complete Substack Primer Guide covering Substack's history, platform architecture, RSS endpoints, and monetization strategies.

⚡ Dual Capabilities: Search/Read & Draft/Publish

substack-mcp is designed for both readers/researchers and creators/publishers:

Workflow Mode	Auth Required?	Capabilities & Features
🔍 Search & Read (Public Mode)	No Login Needed	• Ingest RSS feeds from any Substack newsletter domain• Full-text offline article search in local SQLite• Reader pane & audio/podcast details• Star & bookmark favorite articles
✍️ Draft & Publish (Author Mode)	Requires `substack.sid` Cookie	• Stage, edit, and update Substack post drafts• Convert Markdown to Substack HTML with paywalls (`<!-- paywall -->`)• Local AI Writing Assistant (Ollama, LM Studio)• Subscriber growth metrics, view counts, & open rates• Post comment browsing & reply staging

🚀 Built-in Onboarding & Help

To get you up and running in minutes, substack-mcp includes interactive onboarding directly inside the webapp and in the documentation:

📱 Interactive Webapp Dashboard (http://127.0.0.1:11164):
- Onboarding Tab: Step-by-step setup wizard.
- Help & System Diagnostics Tab: Live health check cards for API Backend (:11163), SQLite DB, Substack Cookie Auth, and Local LLMs.
- Cookie Extractor Tutorial: Visual guide to copy your substack.sid session cookie from Browser DevTools (F12) into Settings.
- MCP Client Integration Snippets: One-click endpoints for Google Antigravity, Claude Desktop, and Cursor.
📚 Repo Guides: See INSTALL.md and docs/ONBOARDING.md.

⚙️ `just` Task Runner Commands

All common tasks are defined in the repository justfile:

# Run full quality check (lint + typecheck + pytest)
just check

# Run Python Pytest test suite
just test

# Lint backend (ruff) and webapp (biome)
just lint

# Format code (ruff format & biome format)
just format

# Static typecheck (pyright & tsc)
just typecheck

# Start unified dev servers (clears zombie ports, starts backend & webapp, opens browser)
just start

# Pack .mcpb desktop package
just mcpb-pack

# Build Tauri NSIS Windows installer
just tauri-build

# Run headless CUA smoke test
just cua-smoke

⚡ Quick Start

1. Launch Server & Webapp Dashboard

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

# Launch backend (11163) and dashboard (11164) via just or PowerShell script
just start
# or: .\start.ps1

The webapp dashboard will automatically open in your default browser at http://127.0.0.1:11164.

2. Connect AI Assistants (Google Antigravity / Claude Desktop)

Point your MCP client configuration to the FastMCP Streamable HTTP endpoint:

http://127.0.0.1:11163/mcp

🛠️ Portmanteau MCP Tools

Tool	Operations	Description
`substack_feed`	`fetch`, `list_publications`, `query`, `get_article`	Ingest RSS feeds, list tracked newsletters, search articles
`substack_drafts`	`create`, `list`, `get`, `update`, `delete`, `convert_markdown`	Stage drafts, edit content, render Markdown HTML
`substack_stats`	`record`, `get`, `summary`	Track subscriber metrics, post views, open rates
`substack_community`	`get_comments`, `post_comment`	Read article comments and stage discussion responses

📁 Sub-Package Documentation

📖 Substack Primer Guide (docs/SUBSTACK_PRIMER.md) — What Substack is, platform structure, history, and ecosystem.
🎨 Webapp Dashboard (webapp/) — Vite, React, Tailwind CSS, and Biome setup.
⚙️ Backend Package (substack_mcp/) — FastAPI, FastMCP 3.1+, Local LLM engine, and SQLite database.
🧪 Test Suite (tests/) — Pytest unit test specifications and coverage.
📜 Scripts (scripts/) — Fleet launchers and prompt generation utilities.
📚 Documentation Hub (docs/) — Complete configuration, onboarding, tools, and troubleshooting guides.

📄 License

Distributed under the MIT License.