Allows an AI client to publish Notes and posts, manage drafts, pull analytics, and bridge Obsidian vault drafts to Substack.
Also known as adelaidasofia/substack-mcp, substack-mcp
- Stars
- 0
- Tools
- 30
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 9, 2026
- License
- MIT
What is Substack MCP?
Substack allows an AI client to publish Notes and posts, manage drafts, pull analytics, and bridge Obsidian vault drafts to Substack. It exposes 30 tools, such as test_connection, list_publications, publish_note.
Summary generated from the project's README
About Substack MCP server
Managing a Substack publication from within an AI client is what this server enables for writers and creators. It allows you to publish Notes and posts, manage drafts, and interact with your reader feed by liking or restacking content. The server connects to your account using a browser session cookie, specifically the substack.sid value, which you provide in a local configuration file.
Beyond simple publishing, the tool integrates with Obsidian vaults to bridge your local markdown drafts directly to your publication. You can use it to pull detailed analytics, such as subscriber growth, revenue, and post engagement, or even snapshot these metrics into your vault. It also supports visual content creation through pluggable image generators like Pillow or Canva to help produce social cards for your posts.
What you can do with it
- 1Publishing local markdown draftsYou can instruct an AI to find and publish specific drafts stored in your Obsidian vault.
- 2Monitoring publication growthAsk the client to retrieve key performance indicators like total subscribers and views.
- 3Automating social media engagementUse the server to quickly post short updates or Notes to your Substack feed.
- 4Generating visual post cardsCreate custom images for your posts using local rendering or design tools.
Written from the project's README. Every use case is checked against a quote from it.
Substack MCP tools 30
Detected from the READMEtest_connectionlist_publicationspublish_notecreate_note_attachmentlist_my_notesreply_to_notelist_vault_draftspublish_vault_draftbatch_publish_vault_draftscreate_draftupdate_draftpublish_post
| test_connection | — | |
| list_publications | — | |
| publish_note | — | |
| create_note_attachment | — | |
| list_my_notes | — | |
| reply_to_note | — | |
| list_vault_drafts | — | |
| publish_vault_draft | — | |
| batch_publish_vault_drafts | — | |
| create_draft | — | |
| update_draft | — | |
| publish_post | — |
Show all 30 toolsShow fewer tools
schedule_postlist_sectionslist_draftslist_publishedget_postupload_imagereactrestackcommentget_feedget_dashboardget_post_statsget_subscriber_growthget_growth_sourcesget_top_postsget_earningsget_recommendation_statscapture_analytics_to_vault
| schedule_post | — | |
| list_sections | — | |
| list_drafts | — | |
| list_published | — | |
| get_post | — | |
| upload_image | — | |
| react | — | |
| restack | — | |
| comment | — | |
| get_feed | — | |
| get_dashboard | — | |
| get_post_stats | — | |
| get_subscriber_growth | — | |
| get_growth_sources | — | |
| get_top_posts | — | |
| get_earnings | — | |
| get_recommendation_stats | — | |
| capture_analytics_to_vault | — |
Configuration
SUBSTACK_SID_COOKIERequiredSecretAuth cookie extracted via browser dev tools
| Name | Description | |
|---|---|---|
| SUBSTACK_SID_COOKIE | Auth cookie extracted via browser dev tools | RequiredSecret |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubsubstack-mcp
FastMCP server for Substack: publish Notes and posts, pull analytics, manage drafts, bridge Obsidian vault drafts to Substack, and generate visual cards with pluggable image generators.
Quick reference
substack__test_connection -- verify auth (start here)
substack__publish_note text=... -- publish a Note immediately
substack__list_vault_drafts -- show drafts from your vault file
substack__publish_vault_draft index=N -- publish one vault draft as a Note
substack__create_draft title=... body=... -- create a post draft
substack__get_dashboard days=30 -- subscriber + view KPIs
substack__capture_analytics_to_vault -- snapshot analytics to vault markdown
Tool inventory (30)
Notes + vault pipeline
test_connection(publication?)-- verify auth, return your profilelist_publications()-- show configured publications and which is defaultpublish_note(text, publication?, attachment_ids?)-- publish a Note immediately; markdown supportedcreate_note_attachment(image_path?, image_url?, link_url?, publication?)-- upload image or register link; returns attachment UUID for use with publish_notelist_my_notes(limit?, publication?)-- your recent Notes with reaction + comment countsreply_to_note(note_id, text, publication?)-- reply to a Note by IDlist_vault_drafts()-- parse vault drafts file, return index + preview for each draftpublish_vault_draft(index, publication?, move_to_published?)-- publish one vault draft as a Notebatch_publish_vault_drafts(indices, publication?)-- publish multiple vault drafts in sequence
Post management
create_draft(title, body, subtitle?, audience?, publication?, section_id?)-- create a post draft; body is markdownupdate_draft(draft_id, title?, body?, subtitle?, audience?, publication?, section_id?)-- edit an existing draftpublish_post(draft_id, send_email?, audience?, publication?, section_id?)-- publish a draft live to subscribersschedule_post(draft_id, publish_at, publication?, section_id?)-- schedule a draft for future publication (ISO 8601)list_sections(publication?)-- list configured sections for a publication; required to publish on publications with sectionslist_drafts(limit?, publication?)-- list unpublished draftslist_published(limit?, publication?)-- list published posts with basic statsget_post(identifier, publication?)-- get full post by slug or numeric IDupload_image(image_path, publication?)-- upload an image to Substack CDN; returns CDN URLreact(post_id, publication?)-- heart a postrestack(post_id, publication?)-- restack a postcomment(post_id, body, publication?)-- comment on a postget_feed(limit?, publication?)-- your reader feed (posts from publications you follow)
Analytics
get_dashboard(days?, publication?)-- KPIs: total/paid subscribers, views, growth, ARRget_post_stats(post_id, publication?)-- views, opens, clicks, shares, conversions for one postget_subscriber_growth(publication?)-- subscriber count over timeget_growth_sources(publication?)-- subscriber growth by source (search, recommendations, direct, social)get_top_posts(limit?, publication?)-- posts ranked by engagementget_earnings(publication?)-- revenue data for paid publicationsget_recommendation_stats(direction?, publication?)-- recommendation network performancecapture_analytics_to_vault(publication?)-- write a weekly analytics snapshot to your vault
Install
Open Claude Code, paste:
/plugin marketplace add adelaidasofia/substack-mcp
/plugin install substack-mcp@substack-mcp
git clone https://github.com/adelaidasofia/substack-mcp
cd substack-mcp
pip3 install -r requirements.txt
python3 -c "import server; print('OK')"
Configuration
Copy config.example.json to config.json and fill in your values:
cp config.example.json config.json
config.json is gitignored. Key fields:
| Field | Description |
|---|---|
publications[].name |
Internal name used in tool calls |
publications[].subdomain |
Your Substack subdomain (e.g. yourname) |
publications[].cookie |
Session cookie (see below) |
default_publication |
Which publication to use when publication arg is omitted |
vault_drafts_path |
Path to your vault drafts markdown file |
image_generator.default |
Active image adapter: pillow_local or canva |
Session cookie setup
Substack does not have a public API with OAuth. Auth uses your browser session cookie.
- Open Chrome and log in to Substack.
- Open DevTools (F12) and go to the Application tab.
- Under Cookies, find
substack.com. - Copy the value of
substack.sid. - Paste it into
config.jsonunder the matching publication'scookiefield.
The raw value works; the server accepts both abc123 and substack.sid=abc123.
Session cookies expire. If tools return {"error": "Auth failed"}, re-extract the cookie.
Register in Claude Code
Add to your .mcp.json (project-scoped) or via claude mcp add -s user:
{
"mcpServers": {
"substack": {
"command": "python3",
"args": ["/path/to/substack-mcp/server.py"]
}
}
}
Restart Claude Code after editing .mcp.json. Verify with claude mcp list.
Vault integration
Set vault_drafts_path in config.json to a markdown file in your Obsidian vault.
Format each draft as a section separated by ---. Sections under ## Ready to Post
are surfaced first by list_vault_drafts. Sections under ## Essay Seeds come next.
After publishing, publish_vault_draft moves the draft to a ## Published section
and appends the Substack URL and timestamp.
Pluggable image generators
Visual card generation is handled by the adapter set in config.json under
image_generator.default.
Shipped adapters
pillow_local (default) -- pure Pillow, no external API. Renders 1080x1080 PNG
cards locally using fonts from the fonts/ directory. Three pillar templates: warm
mustard with optional figure (P1), deep burgundy bold quote (P2), mustard with section
tag (P3). Use with render_card.py as a standalone CLI.
canva -- Canva MCP choreography. Returns a steps list describing the Canva MCP
tool calls needed to clone a template, replace text, replace the figure, and export PNG.
The Claude session executing the playbook follows these steps. Requires Canva MCP
connected in Claude Code and design IDs filled in under image_generator.canva.pillars.
Stubbed adapters (contributions welcome)
nano_banana -- Gemini 3 Pro Image via the nano-banana skill. Stub in
image_generators/nano_banana.py. Implement generate() by calling the skill's
image endpoint with a prompt built from the card spec.
midjourney -- Midjourney API (or proxy). Stub in image_generators/midjourney.py.
Implement generate() by submitting a prompt, polling for completion, and downloading
the result.
dalle -- OpenAI DALL-E. Stub in image_generators/dalle.py. Implement generate()
using openai.images.generate.
Writing your own adapter
Subclass ImageGenerator from image_generators.base:
from image_generators.base import ImageGenerator
class MyAdapter(ImageGenerator):
@property
def name(self) -> str:
return "my_adapter"
def generate(self, spec: dict) -> dict:
# spec keys: pillar, quote, handle, figure_path, output_path
# return: {status: "ok", adapter: ..., image_path: ..., width: ..., height: ...}
...
Register it in image_generators/__init__.py and add a config block under
image_generator.my_adapter in config.json.
Visual publishing pipeline
The visual_helper.py script handles the deterministic side of the visual queue
pipeline: parsing a Review Queue markdown file, rotating through figures, and
marking entries published. See visual_playbook.md for the full end-to-end flow
including image generation, upload, and publishing steps.
python3 visual_helper.py peek --lang es # get next approved visual item
python3 visual_helper.py mark --lang es ... # mark published + update log
python3 visual_helper.py rotate-figure --pillar P1
Known gotchas
-
Cookie expiry.
substack.sidcookies expire after a few weeks. Re-extract from Chrome DevTools whentest_connectionreturns auth errors. -
draft_bylinesis required but undocumented.create_draftwill 400 without it. The server fetches youruser_idfrom/user/profile/selfautomatically and injects it into every draft POST. -
Note attachment endpoint requires trailing slash.
POST /comment/attachment/(with slash) works. Without slash it returns 404. The server handles this correctly. -
Publication-scoped vs global endpoints. Notes use
substack.com/api/v1/comment/feed/. Post drafts use{subdomain}.substack.com/api/v1/drafts. Mixing them returns 404 or 403. -
pledgedArrin the dashboard is a projection, not real pledges. Useget_earningsfor actual revenue data. -
Multi-publication support. Pass
publication="name"to any tool to target a specific publication. Omit it to usedefault_publicationfrom config. -
Sections are required to publish on publications that have them. Substack returns
HTTP 400: Please choose a sectionfrompublish_post/schedule_postwhen the draft hasn't been filed under a section. Look up section IDs withlist_sections(publication="main"), then passsection_id=<id>to either the draft tool or the publish/schedule tool:list_sections # → [{id: 12345, name: "Essays", slug: "essays", ...}, ...] create_draft title=... body=... section_id=12345 # or, for an existing draft: publish_post draft_id=987654 section_id=12345publish_post/schedule_postpatch the draft before publishing, so a single call is enough.
Related MCPs
Same author, same architecture pattern (FastMCP, draft+confirm on writes where applicable, vault auto-export, MIT):
- slack-mcp — multi-workspace Slack
- imessage-mcp — macOS iMessage
- whatsapp-mcp — WhatsApp via whatsmeow
- google-workspace-mcp — Gmail / Calendar / Drive / Docs / Sheets
- apollo-mcp — Apollo.io CRM + sequences
- luma-mcp — lu.ma events
- parse-mcp — markitdown / Docling / LlamaParse router
- rescuetime-mcp — RescueTime productivity data
- graph-query-mcp — vault knowledge graph queries
- graph-autotagger-mcp — wikilink suggestions from the graph
- investor-relations-mcp — seed-raise pipeline tracker
- vault-sync-mcp — bidirectional vault sync
Telemetry
This plugin sends a single anonymous install signal to myceliumai.co the first time it loads in a Claude Code session on a given machine.
What is sent:
- Plugin name (e.g.
slack-mcp) - Plugin version (e.g.
0.1.0)
What is NOT sent:
- No user identifiers, names, emails, tokens, or API keys
- No file paths, message content, or anything from your work
- No IP address is stored after dedup processing
Why: Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.
Opt out: Set the environment variable MYCELIUM_NO_PING=1 before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at ~/.mycelium/onboarded-<plugin> — delete it if you want to reset state.
License
MIT
Built by Mycelium AI. Full install or team version at diazroa.com.
Substack MCP questions
What tools does Substack MCP provide?
It exposes 30 tools, including test_connection, list_publications, publish_note, create_note_attachment, list_my_notes.
What happens if my authentication fails?
Session cookies expire periodically. If you receive an auth error, you will need to re-extract the cookie from your browser.
Does it support multiple publications?
Yes, you can target a specific publication by passing the publication name to any tool, or omit it to use the default configured publication.