Skip to main content
Glama
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.

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


Available Tools

12 tools
analyze_content_patternsAnalyze content-performance patternsA
Read-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 performanceA
Read-onlyIdempotent

Rank posts using normalized, deterministic rates from each post's latest stored snapshot.

Inputs: metric (required), limit, status.

connection_statusSubstack Insights connection statusA
Read-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 pointerA
Read-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 performanceA
Read-onlyIdempotent

Return the latest derived performance rates plus every stored raw metric snapshot for one post.

Inputs: identifier (required).

list_audit_eventsList ledger audit eventsA
Read-onlyIdempotent

Return timestamped RSS imports and local content changes, optionally scoped to one post.

Inputs: limit, identifier.

list_postsList locally tracked postsA
Read-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 versionsA
Read-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 publicationA
Idempotent

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

    A4.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for accessing Substack content including publications, posts, comments, author profiles, recommendations, and Notes feed using your own session token.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local MCP server for managing saved Substack posts. Enables offline reading, searching, bookmarking, and unbookmarking of Substack content via CLI or MCP clients.
      18
      MIT