substack-ops
Standalone Substack CLI + 26-tool MCP server for Cursor MCP, Claude MCP, OpenCode MCP, and any stdio MCP host. Your IDE drafts the replies. Zero AI API keys.
Site → substack-ops.chavan.in · Source → 06ketan/substack-ops · Glama → mcp/servers/06ketan/substack-ops
Posts, notes, comments, replies, reactions, restacks, recommendations, search,
profiles, feeds, automations, MCP server, Textual TUI. One Python install, one
binary, MIT licensed.
TL;DR — MCP-native (no API key, one command)
uvx substack-ops mcp install cursor
Your host's LLM (Cursor's, Claude's) does the drafting via the
propose_reply / confirm_reply tools. No ANTHROPIC_API_KEY /
OPENAI_API_KEY needed.
Wrong install?
This project is substack-ops on PyPI — install with uv / uvx, not unrelated npx packages that appear when searching “Substack MCP”. Canonical listing: Glama — 06ketan/substack-ops.
Works with (MCP)
These rows help discovery (search keywords); confirm each host’s current MCP docs before upgrading.
Open source–oriented hosts
| Host | Documentation | Typical wire-up |
|---|
| OpenCode | OpenCode MCP servers | uvx substack-ops mcp install opencode |
| Continue | Continue | uvx substack-ops mcp install print — paste the snippet into Continue’s MCP settings |
| Zed | Zed | Configure stdio MCP per Zed’s docs |
| Cline | Cline | MCP setup per extension / marketplace docs |
| Goose | Goose | MCP extensions per Goose docs |
Large commercial stacks
| Host | Documentation | Typical wire-up |
|---|
| Cursor | Cursor MCP | uvx substack-ops mcp install cursor |
| Claude (Desktop / Code) | Claude Desktop, Claude Code | mcp install claude-desktop / claude-code |
| GitHub Copilot | Copilot | MCP in VS Code / Copilot where supported — use print + host docs |
| ChatGPT | OpenAI | Developer / connector flows — often REST (Slideshot API) for tools without MCP |
| Google Gemini | Gemini | Gemini CLI / IDE features per Google docs — stdio where supported |
OpenCode (copy-paste)
Auto-install:
uvx substack-ops mcp install opencode
Manual (~/.config/opencode/opencode.json):
{
"mcp": {
"substack-ops": {
"type": "local",
"command": ["uvx", "substack-ops", "mcp", "serve"],
"enabled": true
}
}
}
Optional version pin: use ["uvx", "substack-ops==0.3.5", "mcp", "serve"] (replace with current PyPI release).
Setup (dev / from source)
git clone https://github.com/06ketan/substack-ops && cd substack-ops
uv sync
uv sync --extra mcp
uv sync --extra tui
uv sync --extra chrome
Auth defaults to ~/.cursor/mcp.json's mcpServers.substack-api.env. Override
with env or .env. Or use one of the auth flows in auth login / auth setup.
uv run substack-ops auth verify
uv run substack-ops quickstart
Command surface
Grouped by intent. Every write defaults to --dry-run; flip with
--no-dry-run (and --yes-i-mean-it for the irreversible ones). All writes
land in .cache/audit.jsonl and are dedup-checked against .cache/actions.db.
Auth (4)
| Command | What it does |
|---|
auth verify | Confirm the cookie works; print authed user/pub. |
auth test | Same as verify, exit non-zero on failure (CI-friendly). |
auth login --browser chrome|brave | Auto-grab cookie from local Chromium browser via macOS Keychain. |
auth login --email me@x.com | Email magic-link → paste-the-link interactive flow. |
auth setup | Interactive paste of connect.sid cookie. |
Read — Posts (8)
| Command | What it does |
|---|
posts list [--pub] [--limit] [--sort new|top] | List posts from a publication (yours by default). |
posts show <id|slug> [--pub] | Post metadata (title, dates, reactions, comment count). |
posts get --slug <slug> [--pub] | Same as show but slug-only. |
posts content <id> [--md] [--pub] | HTML body (auth-aware for paywalled). --md converts to Markdown. |
posts stats <id> | Engagement counts — reactions, comments. |
posts search <query> [--pub] [--limit] | Substack-side full-text search. |
posts paywalled <id> [--pub] | Boolean: is this post paywalled? |
posts react <id> [--off] [--pub] | Add (or remove with --off) a reaction. Defaults to ❤. |
posts restack <id> [--off] | Restack a post (Substack does not support unrestack). |
Read — Notes (5)
| Command | What it does |
|---|
notes list [--limit] | Your published Notes. |
notes show <id> | One note + its reply tree. |
notes publish <body> [--no-dry-run] | Publish a top-level Note. |
notes react <id> [--off] | React on any Note. |
notes restack <id> [--off] | Restack a Note. |
| Command | What it does |
|---|
comments tree <post_id> [--pub] | Full nested comment tree as table. |
comments export <post_id> --out file.json [--pub] | Same tree as JSON. |
comments add <post_id> <body> [--pub] [--no-dry-run] | New top-level comment. |
comments react <id> --kind post|note [--off] | React on a comment. |
comments delete <id> --kind post|note [--no-dry-run] | Destructive — your own comments only. |
Reply engine (6)
| Command | What it does |
|---|
reply template <post_id> --template thanks | Rule-based replies (no LLM). |
reply review <post_id> | LLM drafts each, you [a]ccept / [e]dit / [s]kip / [q]uit. |
reply bulk <post_id> --out drafts.json | Draft every comment to a file. Edit, set action: "approved". |
reply note-bulk <note_id> --out drafts.json | Same for replies under a Note. |
reply bulk-send drafts.json [--no-dry-run] | Posts only approved rows. Dedup-checked. |
reply auto <post_id> --no-dry-run --yes-i-mean-it | Draft + post immediately. 30s rate limit. |
Read — Discovery (8)
| Command | What it does |
|---|
feed list --tab for-you|subscribed|category-{slug} | Reader feed (the Substack app feed). |
profile me / profile get <handle> | Profile. |
users get <handle> / users subscriptions <handle> | Public user info + their subs. |
podcasts list [--pub] | Audio posts. |
recommendations list [--pub] | Pub's recommended publications. |
authors list [--pub] | Pub's contributor list. |
categories list / categories get --name <X> | Substack's category taxonomy. |
Automations (3)
| Command | What it does |
|---|
auto presets | List built-in YAML rules. |
auto run <name> | One-shot run a preset. |
auto daemon <name> --interval 60 | Loop forever; logs to audit. |
Operations + safety (3)
| Command | What it does |
|---|
audit search [--kind] [--target] [--status] [--since 7d] | Query the JSONL audit log. |
audit dedup-status | Counts in the dedup SQLite DB. |
quickstart | 20-step interactive tour. |
MCP server (3)
| Command | What it does |
|---|
mcp install <cursor|claude-desktop|claude-code|opencode|print> [--dry-run] | Auto-merge config into your host. |
mcp serve | stdio MCP server (26 tools). |
mcp list-tools | Print the tool registry. |
Other (1)
| Command | What it does |
|---|
tui | Textual TUI — 6 tabs (Notes, Posts, Comments, Feed, Auto, Profile). |
Multi-publication
Every read command accepts --pub <subdomain|domain>. Defaults to your own
publication.
substack-ops posts list --pub stratechery --limit 5
substack-ops posts search "ai" --pub stratechery
substack-ops recommendations list --pub stratechery
Reply modes
| Mode | What it does | Safety |
|---|
template | YAML keyword/regex rules under src/substack_ops/templates/*.yaml | dry-run default |
review | LLM drafts each reply, you [a]ccept / [e]dit / [s]kip / [q]uit | dry-run default + manual gate per comment |
bulk | LLM drafts every comment to drafts.json. Edit file, set action: "approved" | offline review, dedup-checked on send |
bulk-send | Posts only items with action: "approved" | dry-run default; dedup DB prevents the M2 31-dup-replies regression |
auto | LLM drafts and posts immediately | requires --no-dry-run --yes-i-mean-it, 30s rate limit |
After every live note-reply the engine re-fetches the new comment and asserts
ancestor_path is non-empty. If empty, the audit row's result_status is
flipped to "orphaned" (the M2 bug where parent_comment_id was silently
dropped — now caught).
Automations
Built-in presets (auto presets):
- like-back — when someone reacts to your note, react to their latest note.
- auto-reply — same trigger, but post a templated thank-you.
- auto-restack — when a watchlist handle posts a new note, restack it.
- follow-back — when someone follows you, follow them back.
Custom YAML rules under ~/.config/substack-ops/auto/*.yaml. Loop with
auto daemon <name> --interval 60.
MCP server
substack-ops mcp install opencode
substack-ops mcp install cursor
substack-ops mcp install claude-desktop
substack-ops mcp install claude-code
substack-ops mcp install print
substack-ops mcp install cursor --dry-run
substack-ops mcp serve
substack-ops mcp list-tools
Manual config snippet (if you prefer):
{
"mcpServers": {
"substack-ops": {
"command": "substack-ops",
"args": ["mcp", "serve"]
}
}
}
If the mcp SDK is not installed, the server falls back to a minimal
stdin/stdout JSON-line dispatcher that's still useful for scripting:
echo '{"tool":"list_posts","args":{"limit":3}}' | substack-ops mcp serve
MCP-native draft loop (no API key)
3 tools designed to let your host LLM draft for you:
| Tool | What it does |
|---|
get_unanswered_comments | Returns the worklist: comments where you have not yet replied (any depth). |
propose_reply | Dry-run only. Returns a token + payload preview. No write. |
confirm_reply | Posts a previously-proposed reply by token. Idempotent via dedup DB. Token TTL 5 min. |
Differentiator tools (the safety + drafting stack that makes the unattended
mode safe): bulk_draft_replies, send_approved_drafts, audit_search,
dedup_status, get_unanswered_comments, propose_reply, confirm_reply.
LLM strategy
Two layers, both free:
- MCP-native (default). Host LLM drafts via
propose_reply /
confirm_reply. No env vars, no API key. Use this for interactive replies.
- Subprocess CLI (daemon path). For
reply auto / auto daemon when
no human is in the loop. Auto-detects claude (Claude Code),
cursor-agent, or codex on PATH. Override with SUBSTACK_OPS_LLM_CMD.
There is no paid-API-key path. If you want one, vendor the old _anthropic /
_openai methods from substack-ops v0.2.0 yourself.
Textual TUI
6 tabs: Notes / Posts / Comments / Feed / Auto / Profile.
Sub-tabs: 1=mine, 2=following, 3=general.
Keys: tab, 1-3, ↑/↓, enter, r, l, s, o, q/esc.
Auth methods
substack-ops auth verify
substack-ops auth login
substack-ops auth login --browser brave
substack-ops auth login --email me@x.com
substack-ops auth setup
Architecture
mcp.json | env | Chrome | OTP → auth.py / auth_chrome.py / auth_otp.py
│
.cache/cookies.json
│
SubstackClient (httpx)
│
┌──────┬──────┬───────┬───────┬───────┬──────┬──────┬─────┬──────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
posts notes comments feed profile users recs cats ... reply_engine
│
┌───────────────┼────────────┐
▼ ▼ ▼
template ai_review ai_bulk + ai_auto
└───────────────┬────────────┘
▼
base.post_reply / post_note_reply
│
┌────────┼────────┐
▼ ▼ ▼
dedup audit ancestor_path
(SQLite) (jsonl) guardrail
auto/engine.py ────────────────┐
mcp/server.py ──── 23 tools ──┼─── all share SubstackClient
tui/app.py ──── 6 tabs ──┘
Endpoints used
| Action | Method + URL |
|---|
| Auth check | GET https://substack.com/api/v1/subscriptions |
| List posts | GET {pub}/api/v1/archive |
| Post by id | GET {pub}/api/v1/posts/by-id/{id} |
| Post by slug | GET {pub}/api/v1/posts/{slug} |
| Post content | same as above; body_html field |
| Post search | GET {pub}/api/v1/archive?search= |
| Comments | GET {pub}/api/v1/post/{id}/comments?all_comments=true |
| Reply to comment | POST {pub}/api/v1/post/{id}/comment body {body, parent_id} |
| Add top-level comment | same with parent_id: null |
| React to post | POST {pub}/api/v1/post/{id}/reaction body {reaction} |
| Restack post | POST https://substack.com/api/v1/restack body {post_id} |
| Restack note | POST https://substack.com/api/v1/restack body {comment_id} |
| Delete post-comment | DELETE {pub}/api/v1/comment/{id} (PUB host) |
| Delete note | DELETE https://substack.com/api/v1/comment/{id} (BARE host) |
| My notes | GET https://substack.com/api/v1/reader/feed/profile/{user_id} |
| Note thread | GET https://substack.com/api/v1/reader/comment/{note_id} |
| Note replies | GET https://substack.com/api/v1/reader/comment/{note_id}/replies |
| Publish note | POST https://substack.com/api/v1/comment/feed body {bodyJson} |
| Reply to note | same with {bodyJson, parent_id} (NOT parent_comment_id — known M2 bug) |
| React to comment | POST {host}/api/v1/comment/{id}/reaction (host = pub for post-comments, substack.com for notes) |
| Recommendations | GET {pub}/api/v1/recommendations/from/{publication_id} |
| Authors | GET {pub}/api/v1/publication/users/ranked?public=true |
| Categories | GET https://substack.com/api/v1/categories |
| User profile | GET https://substack.com/api/v1/user/{handle}/public_profile (auto-redirects on 404) |
| Reader feed | GET https://substack.com/api/v1/reader/feed/{recommended|subscribed|category/{slug}} |
Tests
Coverage today: auth, client (read+write+engagement+delete), reply engine,
dedup DB, audit log search, MCP tool registry & dispatcher, automation engine
preset loader, the M2 parent_id regression test, the M2 host-mismatch
regression test.
GSD workflow
.planning/ scaffold for Get Shit Done
under ~/.claude/skills/gsd-*. Roadmap at .planning/ROADMAP.md,
per-phase plans at .planning/phases/M*/PHASE.md.
Known gaps
- Full email stats (opens/clicks/views) — needs dashboard CSRF flow. Fallback: Playwright MCP scrape.
- Reactions endpoint shape on POST/DELETE not yet probed live; current shape is a best-guess from upstream tool catalogs.
- Auto-engine
new_follower / new_note_from triggers are stubbed (return note: "trigger not yet implemented").
- TUI sub-tabs (1/2/3) and reply/like/restack key bindings are scaffolded but not wired to the client yet.
- Chrome cookie auto-grab tested only for macOS Chrome; Brave path included; Linux/Windows not supported.
License
MIT. See LICENSE.
The vendored httpx-port helpers under src/substack_ops/_substack/ are derived
from the MIT-licensed NHagar/substack_api package — kept here so this repo
ships zero runtime dependencies on third-party Substack libraries. Attribution
preserved in each file's module docstring.