@abanoub-ashraf/substack-mcp-plus

v1.0.5

Published

11 days ago

Unofficial Substack MCP server. Born from frustration, built with AI. 12 tools, browser auth, rich text support. Not affiliated with Substack Inc.

Substack MCP Plus

An MCP server for Substack that lets AI clients work with your publication and research public Substack content.

It supports:

authenticated account tools for drafts, publishing, scheduling, previews, sections, and post analytics
public research tools for finding, analyzing, and studying Substack posts and publications
content strategy tools for ideas, hooks, repurposing, gap analysis, and series planning

This project is unofficial and is not affiliated with Substack Inc.

What You Can Do

With your own Substack account:

create formatted drafts
update drafts
publish immediately
schedule future posts
list drafts, published posts, and scheduled posts
preview drafts
upload images
inspect sections
read post content
get post analytics

With public Substack content:

research a topic across Substack
analyze a public post URL
analyze a publication URL
create a study plan around a topic
extract coding lessons from public posts

For strategy:

analyze your own posts
generate post ideas
repurpose posts into other formats
run content gap analysis
improve titles and hooks
plan a series

Requirements

Node.js >= 16
Python >= 3.10
a Substack publication URL such as https://yourpublication.substack.com

Install

Install globally with npm:

npm install -g @abanoub-ashraf/substack-mcp-plus

This installs two commands:

substack-mcp-plus
substack-mcp-plus-setup

First-Time Setup

Run the setup wizard:

substack-mcp-plus-setup

The setup flow will:

open a browser
let you sign in to Substack
handle CAPTCHA/manual login flow
store an encrypted browser session locally for later use

The local auth file lives at ~/.substack-mcp-plus/auth.json. The setup stores the browser session cookie jar after login, not your Substack password.

If Substack sends an email sign-in link, open or paste that link in the same browser window opened by substack-mcp-plus-setup. That same-browser step is what lets the setup capture the final authenticated session.

If your client later says authentication failed, run the setup again.

MCP Client Config

Use this server in any MCP client that supports a stdio server definition.

Server block:

{
  "mcpServers": {
    "substack-mcp-plus": {
      "command": "substack-mcp-plus",
      "env": {
        "SUBSTACK_PUBLICATION_URL": "https://YOUR_PUBLICATION.substack.com"
      }
    }
  }
}

If your GUI client does not inherit your shell PATH, use an absolute path instead:

which substack-mcp-plus

Then replace "substack-mcp-plus" with the full path to the binary.

Client Notes

Claude Desktop Config file locations:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\\Claude\\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Claude Code Add the same mcpServers.substack-mcp-plus block to ~/.claude.json.

Codex Add this to ~/.codex/config.toml:

[mcp_servers.substack-mcp-plus]
command = "substack-mcp-plus"

[mcp_servers.substack-mcp-plus.env]
SUBSTACK_PUBLICATION_URL = "https://YOUR_PUBLICATION.substack.com"

Cursor Add the same server block anywhere Cursor expects MCP server JSON.
Antigravity Add the same server block anywhere Antigravity expects MCP server JSON.
Windsurf Add the same server block anywhere Windsurf expects MCP server JSON.
Generic MCP client Use the same stdio definition if the client supports command + env.

After updating the config, fully restart the client.

Tool List

Publishing and Account Tools

create_formatted_post
update_post
publish_post
schedule_post
list_drafts
list_published
list_scheduled_posts
get_post_content
get_post_analytics
duplicate_post
preview_draft
upload_image
delete_draft
get_sections
get_subscriber_count

Public Research Tools

research_substack
research_substack_post
research_substack_publication
study_topic_on_substack
extract_coding_lessons

Strategy Tools

analyze_my_posts
generate_post_ideas
repurpose_post
content_gap_analysis
title_and_hook_optimizer
series_planner

Example Prompts

Account Workflows

List my latest drafts
Show me my scheduled posts
Get the content of draft 123456
Create a draft titled "Why SwiftUI image caching matters" with markdown content
Schedule draft 123456 for 2026-03-12T09:00:00Z
Show analytics for published post 123456

Research Workflows

Research Substack for swiftui image caching
Research this Substack post: https://www.oneusefulthing.org/p/change-blindness
Research this publication: https://oneusefulthing.substack.com
Study SwiftUI performance on Substack
Extract coding lessons from https://example.substack.com/p/some-post

Strategy Workflows

Analyze my posts
Generate post ideas for indie iOS app marketing
Repurpose my latest draft into a Twitter thread
Improve the title and hook for post 123456
Plan a 5-part series on Swift concurrency

Notes About Confirmation

Some write actions are intentionally confirmation-oriented. For high-impact actions like create, update, publish, schedule, duplicate, and delete, the client should confirm before the final action is sent.

Known Limitations

These are the current honest limits, not marketing wallpaper:

get_subscriber_count may return an unavailable state if Substack does not expose a reliable count through publication metadata, page markup, or section data.
Public research works best on focused queries such as swiftui image caching or ios concurrency rather than very broad topics.
Broad-topic discovery can still have lower recall than niche queries.
study_topic_on_substack and extract_coding_lessons(query=...) depend on the quality of the underlying discovery results.
Public research tools only work on public pages that are reachable and parseable.

Troubleshooting

Command not found

Your client may not inherit your shell PATH.

Find the installed binary:

which substack-mcp-plus

Then use the absolute path in the client config.

Authentication failed

Run setup again:

substack-mcp-plus-setup

If Substack sent a sign-in email, paste the email link into the same setup browser window before closing it.

MCP shows connected but tools do not appear

This is usually a client session cache issue.

Do this:

fully quit the MCP client
reopen it
start a fresh session

Research results are weak or empty

Try a narrower query.

Better:

swiftui image loading
swiftui asyncimage
ios monetization

Usually weaker:

AI for work
coding
productivity

GUI client still cannot launch the server

Use an absolute command path instead of substack-mcp-plus.

Development

Install editable Python dependencies in the project venv:

./venv/bin/python -m pip install -e '.[dev]'

Run tests:

./venv/bin/python -m pytest -q

Run the server directly:

node src/index.js

Security

Do not commit tokens, passwords, or private keys.
Prefer interactive setup over hardcoded credentials.
Stored browser session data is encrypted under ~/.substack-mcp-plus/.
Use obvious placeholders in configs and examples.
Re-run authentication if a stored Substack session expires.

See SECURITY.md for project security notes.

License

MIT