Standalone Substack CLI + 26-tool MCP server. Your IDE drafts the replies. Zero AI API keys.

Project description

substack-ops

Standalone Substack CLI + 26-tool MCP server. Your IDE drafts the replies. Zero AI API keys.

Site → substack-ops.chavan.in · Source → 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          # or claude-desktop, claude-code, print
# Restart your host. Then in chat:
#   "list unanswered comments on post 193866852"
#   "draft a warm reply to comment 12345"
#   "post that draft"

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.

Setup (dev / from source)

git clone https://github.com/06ketan/substack-ops && cd substack-ops
uv sync
uv sync --extra mcp     # mcp SDK for the MCP server (recommended)
uv sync --extra tui     # textual for the TUI
uv sync --extra chrome  # pycryptodome + keyring for Chrome cookie auto-grab

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   # 20-step tour

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.

Read + Write — Comments (5)

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\|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 cursor              # auto-add to ~/.cursor/mcp.json
substack-ops mcp install claude-desktop      # auto-add to claude_desktop_config.json
substack-ops mcp install claude-code         # uses `claude mcp add` under the hood
substack-ops mcp install print               # print the snippet only
substack-ops mcp install cursor --dry-run    # preview without writing
substack-ops mcp serve                       # stdio server
substack-ops mcp list-tools                  # 26 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

substack-ops 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                  # uses mcp.json or env
substack-ops auth login                   # auto-grab cookies from Chrome (macOS Keychain)
substack-ops auth login --browser brave
substack-ops auth login --email me@x.com  # email magic-link, paste-the-link mode
substack-ops auth setup                   # interactive paste cookies

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

uv run pytest -q     # 43 tests, ~0.6s, no live network

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.

Project details

Release history Release notifications | RSS feed

This version

0.3.3

Apr 21, 2026

0.3.2

Apr 21, 2026

0.3.1

Apr 21, 2026

0.3.0

Apr 21, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

substack_ops-0.3.3.tar.gz (50.2 kB view details)

Uploaded Apr 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

substack_ops-0.3.3-py3-none-any.whl (65.3 kB view details)

Uploaded Apr 21, 2026 Python 3

File details

Details for the file substack_ops-0.3.3.tar.gz.

File metadata

Download URL: substack_ops-0.3.3.tar.gz
Upload date: Apr 21, 2026
Size: 50.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for substack_ops-0.3.3.tar.gz
Algorithm	Hash digest
SHA256	`132f249aa7e38225d3d0245a6e3c5b8391a06d2efe99e79ce465ed74cabc8eff`
MD5	`56829b9f233981f17c137594c9ee4aa9`
BLAKE2b-256	`570e8f1643862ffb653e77358181a3a8572c6322bf89896af6aade4842422b04`

See more details on using hashes here.

File details

Details for the file substack_ops-0.3.3-py3-none-any.whl.

File metadata

Download URL: substack_ops-0.3.3-py3-none-any.whl
Upload date: Apr 21, 2026
Size: 65.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for substack_ops-0.3.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`798402c7e09a2039fb6c1d041c0eb78c925e65ec0bd055c750e98469812d6071`
MD5	`218689f59e25e23eae0f40f68ea04bc3`
BLAKE2b-256	`fbb1a761f41e77f6bd42c69b4c5d23ce15641ad47679c07cb2e52f05bb9012e5`

See more details on using hashes here.

substack-ops 0.3.3

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

substack-ops

TL;DR — MCP-native (no API key, one command)

Setup (dev / from source)

Command surface

Auth (4)

Read — Posts (8)

Read — Notes (5)

Read + Write — Comments (5)

Reply engine (6)

Read — Discovery (8)

Automations (3)

Operations + safety (3)

MCP server (3)

Other (1)

Multi-publication

Reply modes

Automations

MCP server

MCP-native draft loop (no API key)

LLM strategy

Textual TUI

Auth methods

Architecture

Endpoints used

Tests

GSD workflow

Known gaps

License

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes