mcp-substack

Local MCP server for giving Copilot access to Substack posts that your own reader account is allowed to view, including paid posts from your subscriptions.

The main workflow is daily summary generation:

1. Sync recent posts from priority Substack publications.
2. Cache metadata and markdown locally.
3. Let Copilot list unsummarized posts.
4. Let Copilot fetch long posts in chunks.
5. Mark summarized posts so they do not repeat tomorrow.

Safety Boundary

This server uses only your own authenticated Substack session.

It does not:

• read your normal Chrome profile
• read Chrome Keychain-backed cookie storage
• store your Substack password
• bypass paywalls
• share paid content outside your machine

Authentication is handled through a dedicated Playwright browser profile:

~/Library/Application Support/mcp-substack/browser-profile/

Cached article data is stored locally:

~/Library/Application Support/mcp-substack/substack.db

Local config is stored at:

~/Library/Application Support/mcp-substack/config.json

Requirements

• macOS
• Node.js 26 or newer recommended, because this project uses Node's built-in node:sqlite
• npm

Install

cd ~/path/to/substack-mcp
npm install
npx playwright install chromium
npm run build

First Login

Open the dedicated Substack browser profile and log in once:

npm run spike -- login 300

If you are already logged in, the browser may open briefly and close.

Check login status:

npm run spike -- status

Expected result:

{
  "loggedIn": true
}

Priority Publications

You can optionally configure a small set of priority publications for daily summary runs. This is useful when you subscribe to many publications but only want a subset in the default summary.

Set or reset priority publications with your own publication URLs:

npm run spike -- config-priority \
  https://example-newsletter.substack.com \
  https://example.com

Show current config:

npm run spike -- config-show

Local Sync Commands

Sync only priority publications:

npm run spike -- sync-priority 3 5

This means:

• last 3 days
• up to 5 recent posts per priority publication
• fetch full article bodies into the local cache

List cached unsummarized posts:

npm run spike -- cache-list 20

Useful diagnostics:

npm run spike -- discover
npm run spike -- list-posts https://example-newsletter.substack.com 5

MCP Server

Build and run the MCP server over stdio:

npm run build
npm start

Example MCP client config:

{
  "servers": {
    "substack": {
      "command": "node",
      "args": [
        "/absolute/path/to/substack-mcp/dist/server.js"
      ]
    }
  }
}

Daily Copilot Workflow

Recommended tool sequence:

1. substack_sync_recent

   {
     "days": 3,
     "limitPerPublication": 5,
     "priorityOnly": true,
     "fetchContent": true
   }
   

2. substack_list_posts

   {
     "summarized": false,
     "limit": 20
   }
   

3. For each post to summarize, call substack_get_post_chunks.

   {
     "postKeyOrUrl": "<postKey from substack_list_posts>",
     "maxChars": 8000
   }
   

4. After generating the daily summary, call substack_mark_summarized.

   {
     "postKeyOrUrls": ["<postKey>", "<postKey>"],
     "summaryDate": "2026-06-30"
   }
   

MCP Tools

• substack_login

  • Opens the dedicated browser profile and waits for Substack login.

• substack_sync_status

  • Shows app paths, config, and login status.

• substack_config_show

  • Shows local config.

• substack_config_set_priority_publications

  • Sets priority publication URLs.

• substack_config_set_defaults

  • Sets default sync window and per-publication limit.

• substack_discover_subscriptions

  • Discovers publications from the authenticated reader account.

• substack_sync_recent

  • Syncs recent posts into SQLite.

• substack_list_posts

  • Lists cached post metadata. This does not return full bodies.

• substack_get_cached_post

  • Returns one cached post with markdown.

• substack_get_post_chunks

  • Returns one cached post split into bounded markdown chunks.

• substack_mark_summarized

  • Marks posts as included in a daily summary.

• substack_list_recent_posts

  • Diagnostic tool for listing recent posts from one publication.

• substack_get_post

  • Diagnostic tool for live-fetching one post as markdown.

Verification Status

Current verified behavior:

• dedicated browser profile login works
• subscription discovery works
• paid full text works for authorized subscriptions
• priority-only sync works
• SQLite cache stores metadata and markdown
• chunking works for long articles
• npm run typecheck passes
• npm run build passes

Troubleshooting

Browser Opens and Closes Quickly

This usually means the dedicated profile is already logged in and the login check succeeded.

Run:

npm run spike -- status

Playwright Browser Missing

Run:

npx playwright install chromium

Substack Returns 429

Substack may rate-limit repeated sync attempts. Wait a few minutes and retry with a smaller window:

npm run spike -- sync-priority 3 2

Paid Post Shows Preview Only

Check that the dedicated profile is logged into the account with the paid subscription:

npm run spike -- status

Then test the publication directly:

npm run spike -- list-posts https://example-newsletter.substack.com 5

Reset Local State

The local data lives outside the repository:

~/Library/Application Support/mcp-substack/

Remove only the files you intend to reset. Deleting browser-profile/ requires logging into Substack again. Deleting substack.db removes cached articles and summary state.