📰 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.

Related MCP server: Substack Reader MCP Server

⚡ Dual Capabilities: Search/Read & Draft/Publish

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

🚀 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

📁 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.