substack-insights-mcp
Provides tools for archiving and analyzing Substack publication content and metrics, including syncing the public RSS archive, maintaining immutable content versions, recording metric snapshots from Substack's official analytics, comparing post performance, and analyzing content patterns.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@substack-insights-mcp Show me my top 5 posts by subscriptions per 1,000 delivered"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: substack-mcp
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 .envSet your publication origin in .env:
SUBSTACK_PUBLICATION_URL=https://your-publication.substack.com
SUBSTACK_INSIGHTS_DB_PATH=./data/substack-insights.sqliteThen build, test, and import the public archive:
npm run check
npm test
npm run build
node dist/src/cli.js syncAdd 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 serveFor 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_officialThen 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 withsubstack_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 |
| Configuration, ledger counts, and sync freshness |
| Import the public RSS archive |
| Browse canonical post records and latest digests |
| Retrieve exact latest content for one post |
| Inspect immutable version history |
| Review imports and local content changes |
| Persist values observed through the official MCP |
| Get raw history plus derived rates |
| Rank comparable posts deterministically |
| Calculate content/performance correlations |
| Start versioned local Markdown—without publishing |
| 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
Local first. SQLite is the system of record and its file is restricted to the current user.
Immutable history. New content creates a version; it does not rewrite what was previously observed.
Provenance always. Metrics carry a source and capture time. Unknown stays
null.Deterministic math. Rankings and rates are ordinary code, covered by tests.
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.
Available Tools
12 toolsanalyze_content_patternsAnalyze content-performance patternsARead-onlyIdempotent
Calculate correlations between performance and word count, title length, and UTC send hour. Requires at least three measured posts.
Inputs: metric (required).
compare_postsRank comparable post performanceARead-onlyIdempotent
Rank posts using normalized, deterministic rates from each post's latest stored snapshot.
Inputs: metric (required), limit, status.
connection_statusSubstack Insights connection statusARead-onlyIdempotent
Show publication configuration, local ledger counts, and synchronization freshness.
Inputs: no named parameters.
create_local_draftCreate an immutable local draft versionA
Create local Markdown content in the immutable ledger. This never contacts or publishes to Substack.
Inputs: title (required), markdown (required), subject, subtitle, +1 more.
get_postGet exact post content and history pointerARead-onlyIdempotent
Return the canonical record and latest immutable content version for a local id, remote id, slug, canonical URL, or exact title.
Inputs: identifier (required).
get_post_performanceGet post performanceARead-onlyIdempotent
Return the latest derived performance rates plus every stored raw metric snapshot for one post.
Inputs: identifier (required).
list_audit_eventsList ledger audit eventsARead-onlyIdempotent
Return timestamped RSS imports and local content changes, optionally scoped to one post.
Inputs: limit, identifier.
list_postsList locally tracked postsARead-onlyIdempotent
List canonical post records and content-version digests. This omits full bodies; use get_post for exact content.
Inputs: limit, status.
list_post_versionsList immutable post versionsARead-onlyIdempotent
Return the stored content-version history for one post, newest first, including exact bodies and SHA-256 digests.
Inputs: identifier (required), limit.
record_metric_snapshotRecord an official MCP metric snapshotA
Store timestamped metrics obtained from Substack's official MCP against an existing post. Never enter estimates.
Inputs: identifier (required), sent, likes, opens, +12 more.
sync_publicationSynchronize Substack publicationAIdempotent
Import the publication's public RSS archive into the local immutable ledger. No credentials are used.
Inputs: no named parameters.
update_local_draftCreate a new local draft versionA
Update selected local draft fields by appending an immutable version. Existing sent versions cannot be changed.
Inputs: postId (required), title, subject, markdown, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: listing vs retrieving posts, managing versions, tracking metrics, comparing posts, analyzing patterns, and handling drafts. Even potentially similar tools like get_post and list_post_versions are clearly differentiated by latest vs full history.
Most tools follow a consistent verb_noun pattern (list_posts, get_post, record_metric_snapshot, create_local_draft). The only outlier is connection_status, which is a noun phrase rather than a verb-oriented name, making it slightly inconsistent.
12 tools is well within the ideal range for a focused server. Each tool earns its place by covering a distinct aspect of the publication insight workflow: syncing, querying, versioning, auditing, metrics, analysis, and drafts.
The toolset covers the full lifecycle for content ingestion (sync), retrieval (list/get), version history, audit, metric recording/analysis, and draft management. Minor gaps like explicit list/delete for drafts are mitigated by the immutable ledger design and list_posts coverage, but a dedicated draft listing would improve completeness.
Maintenance
Related MCP Connectors
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
Bluesky posts, profiles, feeds, threads & Substack newsletter search and publication feed MCP API.
Bluesky posts, profiles, feeds, threads & Substack newsletter search and publication feed MCP API.
Blog MCP server for AI agents. One signup call returns a blog, an API key and a live URL; then your agent publishes markdown posts and gets public URLs back. Your agent does the writing; you get a dashboard for stats.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for Substack's official Publisher API that enables querying post analytics, subscriber counts, and publication data through natural language from MCP clients.76MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for accessing Substack content including publications, posts, comments, author profiles, recommendations, and Notes feed using your own session token.4MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Substack that enables reading articles, comments, feed, and subscriptions from AI clients like Cursor and Claude, with optional authentication for paid content.64 npm5MIT
- AlicenseAqualityBmaintenanceA local MCP server for managing saved Substack posts. Enables offline reading, searching, bookmarking, and unbookmarking of Substack content via CLI or MCP clients.18MIT