substack-insights-mcp

<p align="center"> <img src="./docs/assets/hero.svg" alt="Substack Insights MCP — your publication's memory, local, exact, and queryable" width="100%" /> </p>

<p align="center"> <a href="https://github.com/jakewlittle-cs/substack-insights-mcp/actions/workflows/ci.yml"><img src="https://github.com/jakewlittle-cs/substack-insights-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://github.com/jakewlittle-cs/substack-insights-mcp/releases"><img src="https://img.shields.io/github/v/release/jakewlittle-cs/substack-insights-mcp?display_name=tag&sort=semver&color=ff6719" alt="Latest release" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-6366f1" alt="Apache-2.0 license" /></a> <img src="https://img.shields.io/badge/Node.js-%E2%89%A522.5-22c55e" alt="Node.js 22.5 or newer" /> <img src="https://img.shields.io/badge/Substack%20access-public%20RSS%20only-0f172a" alt="Public RSS only" /> </p>

<p align="center"><strong>A credential-free MCP server that turns a publication's public archive and official analytics snapshots into durable, explainable intelligence.</strong></p>

<p align="center"> <a href="#quick-start">Quick start</a> · <a href="#the-toolbox">Tools</a> · <a href="#pair-it-with-substacks-official-mcp">Official MCP bridge</a> · <a href="./docs/ARCHITECTURE.md">Architecture</a> · <a href="./CONTRIBUTING.md">Contributing</a> </p>

[!IMPORTANT] This is an independent, unofficial project. It never signs in to Substack, accepts no Substack cookies, calls no private endpoints, and cannot publish. Use it only with a publication you own, administer, or have permission to archive.

Why this exists

An RSS feed tells you what went out. Substack's official MCP can tell you how it performed. Neither gives your assistant a durable, versioned memory that it can query next month.

Substack Insights MCP joins those pieces locally:

flowchart LR
    RSS[Public RSS archive] -->|exact HTML + text| LEDGER[(SQLite ledger)]
    OFFICIAL[Substack official MCP] -->|timestamped metric snapshot| LEDGER
    DRAFT[Local Markdown] -->|immutable versions| LEDGER
    LEDGER --> ANALYTICS[Deterministic analytics]
    ANALYTICS --> MCP[12 MCP tools]
    MCP --> CLIENT[Codex · Claude · Cursor · any MCP client]

Everything important is stored as a fact: exact content, SHA-256 digests, capture times, metric sources, and raw snapshot values. The model can interpret the results; it cannot silently invent the arithmetic.

What you get

Archive	Analytics	Trust boundary
Exact RSS HTML and searchable text	Open rate and normalized conversion rates	No credentials or private APIs
Immutable local Markdown versions	Post rankings on comparable metrics	SQLite stays on your machine
SHA-256 content fingerprints	Word-count, title-length, and send-hour correlations	Missing metrics remain missing
Timestamped audit trail	Full metric history instead of latest-value overwrite	No remote writes—ever

Quick start

Requirements: Node.js 22.5 or newer.

git clone https://github.com/jakewlittle-cs/substack-insights-mcp.git
cd substack-insights-mcp
npm ci
cp .env.example .env

Set your publication origin in .env:

SUBSTACK_PUBLICATION_URL=https://your-publication.substack.com
SUBSTACK_INSIGHTS_DB_PATH=./data/substack-insights.sqlite

Then build, test, and import the public archive:

npm run check
npm test
npm run build
node dist/src/cli.js sync

Add it to Codex

Use absolute paths for the executable and database:

codex mcp add substack_insights \
  --env SUBSTACK_PUBLICATION_URL=https://your-publication.substack.com \
  --env SUBSTACK_INSIGHTS_DB_PATH=/absolute/path/substack-insights.sqlite \
  -- node /absolute/path/substack-insights-mcp/dist/src/cli.js serve

For another client, configure the equivalent stdio command:

{
  "command": "node",
  "args": ["/absolute/path/substack-insights-mcp/dist/src/cli.js", "serve"],
  "env": {
    "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com",
    "SUBSTACK_INSIGHTS_DB_PATH": "/absolute/path/substack-insights.sqlite"
  }
}

Pair it with Substack's official MCP

Substack's official MCP exposes private publication analytics through OAuth for eligible publication admins. Install it beside this server:

codex mcp add substack_official --url https://mcp.substack.com/api/v1/mcp
codex mcp login substack_official

Then ask your agent:

Using substack_official, get the latest metrics for my recent posts. Match each result to the local archive and save every observed value with substack_insights.record_metric_snapshot. Then rank posts by subscriptions per 1,000 delivered and explain the strongest content patterns.

The agent is the bridge: it reads authoritative values from the official connector and records them here with source official_mcp and a capture timestamp. This project never receives or stores the official connector's OAuth token. See the snapshot workflow.

The toolbox

Tool	Purpose
connection_status	Configuration, ledger counts, and sync freshness
sync_publication	Import the public RSS archive
list_posts	Browse canonical post records and latest digests
get_post	Retrieve exact latest content for one post
list_post_versions	Inspect immutable version history
list_audit_events	Review imports and local content changes
record_metric_snapshot	Persist values observed through the official MCP
get_post_performance	Get raw history plus derived rates
compare_posts	Rank comparable posts deterministically
analyze_content_patterns	Calculate content/performance correlations
create_local_draft	Start versioned local Markdown—without publishing
update_local_draft	Append a new immutable local version

Analytics that show their work

• open_rate: supplied value, or opens divided by delivered when absent.
• subscriptions_per_1000: signups—or free plus paid subscriptions—per 1,000 delivered.
• views_per_1000: views per 1,000 delivered.
• engagement_rate: likes plus comments plus shares, divided by views.
• content_patterns: Pearson correlations against word count, title length, and UTC send hour, with an explicit causation warning.

Comparisons use each post's latest stored snapshot. For sound conclusions, compare similar audiences at similar measurement ages.

Design promises

1. Local first. SQLite is the system of record and its file is restricted to the current user.
2. Immutable history. New content creates a version; it does not rewrite what was previously observed.
3. Provenance always. Metrics carry a source and capture time. Unknown stays null.
4. Deterministic math. Rankings and rates are ordinary code, covered by tests.
5. A narrow network boundary. The only Substack request is a public RSS GET.

Read the architecture, operations guide, and security model for details.

Project status

v0.1.0 is the first public release. The storage format and MCP tool contracts are intentionally small and tested, but pre-1.0 APIs may evolve with release notes and migrations.

Contributions are welcome. Start with CONTRIBUTING.md, report security issues through SECURITY.md, and see the roadmap for good first directions.

---

<p align="center"> Built for publishers who want their archive to become institutional memory—not another disposable dashboard. </p>