podcast_server
An MCP server for managing and publishing Substack drafts.
Create or update Substack drafts from Markdown with title, subtitle, audience, comment permissions, SEO fields, slug, section, tags, and optional prepublish/publish.
List publications and list/get drafts.
Update existing drafts by ID, add tags, and run prepublish checks.
Publish drafts, including a safer checked path that requires explicit confirmation and validation; optionally send email and auto-share.
Schedule or unschedule drafts.
Check authentication status and available publications.
Integrates with Cloudflare R2 for storing podcast audio and media on your own domain, and with Cloudflare metrics for collecting episode/download analytics.
Crossposts companion blog posts to dev.to as unpublished drafts, keeping the original on your own site.
Backs up the podcast catalog and show data to a private Hugging Face repository.
Crossposts companion blog posts to Substack as unpublished drafts, keeping the original on your own site.
Publishes episodes to YouTube, sets video thumbnails, and collects YouTube metrics for published content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@podcast_server Prep the Ada interview from Descript and draft show notes for my review"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
podcast_server
A self-hosted podcast host with no dashboard. Your AI agent is the interface. You're the approver.
What it is · How it works · Quick start · MCP tools · Adopting guide · Agent guide
What it is
Podcast hosts charge a monthly fee for three things: storage for the audio, a database of episodes, and an RSS feed, all behind a web dashboard. podcast_server keeps those three on infrastructure you own and replaces the dashboard with MCP tools. The "user interface" is whichever AI agent you already use: Claude, Cursor, Codex, or your own.
You talk to your agent: "The interview with Ada is ready in Descript. Prep it." The agent stages the episode, drafts titles and show notes in your show's voice, and stops. You approve. The agent publishes, uploads the video, sets the thumbnail, posts the announcement, asks search engines to crawl the new pages, copies the companion blog post to dev.to, Hashnode, and Substack (your site stays the original), and tells you a week later how it's doing.
flowchart LR
subgraph hosted["A hosting service"]
direction TB
Y1([You]) -->|click through| D[Their web dashboard]
D --> S1[(Their storage)]
D --> C1[(Their database)]
D --> F1[Their feed URL]
end
subgraph self["podcast_server"]
direction TB
Y2([You]) <-->|chat and approve| A[Your AI agent]
A -->|MCP tools| E[podcast_server]
E --> S2[(Your R2 bucket)]
E --> C2[(Your SQLite catalog)]
E --> F2[Feed on your domain]
end
hosted ~~~ selfHow to place it:
Question | Answer |
What job does it do? | Podcast hosting and publishing: storage, feed, catalog, distribution, and analytics |
Where does it run? | On your machine, against services you own: Cloudflare R2, your domain, and optionally a git-deployed website |
How do you operate it? | Through an AI agent over MCP. There is no web UI. |
Who decides? | You. The agent drafts and executes; nothing public happens without your approval. |
Closest category | A headless podcast host: like a headless CMS, where the missing "head" is an agent |
What it isn't:
Not an editor. Edit in Descript, or anything that exports an MP3. The engine takes it from there.
Not an AI that makes your show. The engine has no taste, on purpose. Your playbook holds the voice and standards, the agent applies them, and you approve.
Not a hosted service. Nobody runs it for you, and there's no account to sign up for.
Not a wrapper around someone else's product. It is the system of record: the catalog, the episode GUIDs, the published audio, and the log of every public action live here.
New here? Start with ADOPTING.md, a step-by-step guide to running your own show, including migrating from another host without losing subscribers.
Related MCP server: unified-ai-system
How it works
Three layers, two people
flowchart TB
YOU([You: taste and approval]) <--> AGENT([Your AI agent: drafts and executes])
AGENT -->|reads first| SHOW
AGENT -->|calls| SURFACE
subgraph SHOW["Show layer: your private DATA_DIR"]
PB[PLAYBOOK.md: voice, title rules, workflows]
TPL[templates: social posts, thumbnail style]
CAT[(catalog.db and logs of every public action)]
end
subgraph SURFACE["Surface: the MCP server"]
TOOLS[typed tools with safety annotations]
RULES[operating rules sent on connect, AGENTS.md]
end
subgraph ENGINE["Engine: show-neutral Python"]
CORE[core: catalog, storage, feed, site, discovery checks, art, doctor, capabilities]
IO[importers and exporters: RSS, Descript, YouTube, X, Instagram, dev.to, Hashnode, Substack]
MET[metrics: OP3, Cloudflare, X, Instagram, YouTube, dev.to, Hashnode, Substack]
end
subgraph OWNED["Services you own"]
R2[(Cloudflare R2 on your domain)]
WEB[your website repo]
PLAT[YouTube, X, Instagram, dev.to, Hashnode, and Substack accounts]
HF[(private Hugging Face backup)]
end
SURFACE --> ENGINE
CORE --> CAT
CORE --> R2
CORE --> WEB
CORE --> HF
IO --> PLAT
MET --> PLATLayer | Its job | Where it lives |
Engine | The hands: does each job correctly and refuses unsafe ones | this repo: |
Surface | The controls: typed tools, safety annotations, operating rules |
|
Show | The taste and the memory: voice, templates, catalog, logs | your private |
The engine and surface know nothing about any particular show. That's why this repo can be public while your show data stays private, and why one checkout can run several shows (one .env each).
A release, end to end
sequenceDiagram
actor You
participant Agent as Your AI agent
participant MCP as podcast_server
participant Svc as Your services
You->>Agent: The episode with Ada is ready in Descript
Agent->>MCP: podcast_stage_from_descript
MCP->>Svc: download the master audio
MCP-->>Agent: measured audio, chapters, draft show notes
Agent->>Agent: titles, notes, and a discovery brief in the playbook's voice
Agent->>MCP: podcast_render_thumbnail and podcast_render_episode_art
Agent-->>You: review package: titles, notes, brief next to each channel's fields, art
You->>Agent: approved, with edits
Agent->>MCP: podcast_stage_discovery
Agent->>MCP: podcast_publish with transcript and episode art
MCP->>MCP: check slug, GUID, exclusions, discovery fields, files, and audio before any upload
MCP->>Svc: upload audio, transcript, chapters, and art to R2, rebuild feed and pages, deploy
MCP-->>Agent: live URLs and deploy status
Agent->>MCP: podcast_backup
Agent-->>You: published, with linksAfter release: promote and measure
Every public action is logged, and metrics only count what the engine itself put out, so numbers are never mixed with the rest of your accounts:
flowchart LR
P[published episode] --> V[YouTube upload and thumbnail]
P --> X[X post]
P --> IG[Instagram post]
P --> DT[dev.to, Hashnode, and Substack blog copies]
V --> L[(logs in DATA_DIR/social)]
X --> L
IG --> L
DT --> L
L --> C[daily collectors: OP3, Cloudflare, X, Instagram, YouTube, dev.to, Hashnode, Substack]
C --> M[(metrics.db)]
M --> D[offline dashboard and metrics tools]
D -->|"how is the show doing?"| AG([your agent])Safety lives in the engine, not the prompt
An agent can misread a prompt; it can't get past code. The rules that matter are enforced by the engine itself: a database trigger blocks excluded episodes, publishing checks everything before the first upload, uploads never overwrite, and every public action is logged so a retry can't double-post. On top of that, every tool carries MCP annotations, so your client can run reads freely and ask you before anything public:
Level | What your client can do | Tools |
Read-only | run without asking |
|
Local files | run without asking |
|
Outside services, additive | run, safe to retry |
|
Public edit | ask you first; safe to retry |
|
Public release | ask you first; never repeat blindly |
|
Design principles
You own the infrastructure. Audio sits in your bucket, the feed on your domain, the catalog in a file you can open. Leaving means copying files, not exporting from someone's dashboard.
The agent operates; you approve. Nothing goes public without your explicit approval of the exact content. When a request is unclear, an identifier doesn't match exactly, or a step would bypass a tool, the agent asks instead of guessing, and it says up front what the engine can't do.
Guarantees live in code. GUIDs are permanent, exclusions are enforced by the database, and checks run before side effects.
Everything is inspectable. SQLite, Markdown, JSON, and append-only JSONL logs. No hidden state.
The engine is show-neutral. Your voice, templates, and data live in your own
DATA_DIR, never in this repo.
Features
Feed: RSS 2.0 + iTunes + Podcasting 2.0 (
<podcast:locked>,<podcast:guid>), exact enclosure byte lengths, Markdown show notes rendered tocontent:encoded, optional OP3 analytics.Two site modes:
noneserves the feed from your R2 domain, with no website needed.astrowrites one Markdown page per episode into your site repo and pushes only those files.Migration: a GUID-preserving importer for any host's RSS feed, with audio mirrored into R2.
Agent surface: MCP tools covering staging (including Descript), publishing, episode edits, deploys, backups, blog posts, social drafts, X and Instagram posts, media uploads, YouTube uploads and thumbnails, and audience metrics. Each tool carries MCP safety annotations (read-only, destructive, idempotent), and the server sends its operating rules to every client on connect, including when to stop and ask the human.
podcast_capabilitiestells the agent which channels are ready right now, and which requests need the human, so it can show you what's possible before planning the work.Discovery at publish time: each piece of content gets one approved brief (main search phrase, secondary phrases, audience, the question it answers, names people search for), and every publish path checks its own fields against it before anything goes public. That covers the episode title and summary, the blog's meta description, YouTube's title, the first 150 characters of the description, tags, and chapters, alt text and the visible start of an Instagram caption, and alt text and, for episode posts, a brief phrase in the text on X. A miss is refused, not warned about. New episodes also carry a transcript (
podcast:transcript, which Apple displays), a chapters file, and their own artwork in the feed; YouTube uploads get a caption track and a playlist. Applies to content published from now on; nothing already published is changed.Blog cross-posting: your site keeps the original; the companion blog post goes to dev.to and Hashnode (as a draft, or live with
publish=true) and to Substack (as a draft), with site-relative links made absolute, the post's FAQ as a section, and an optional footer of your own (bio, links). dev.to and Hashnode copies carry a canonical URL back to your site (Hashnode copies also keep the post's SEO title, description, and original publish date); Substack has no canonical setting, so its drafts open with an "Originally published at" link. You publish Substack drafts in its editor.Search engines and site rules: every deploy that pushes pages asks Bing, Yandex, and the other IndexNow engines to crawl them, once each page answers HTTP 200 (Google reads your sitemap instead). An optional
site_rules.jsonin yourDATA_DIRmakes blog posts meet your site's own standards before they go live: tags from your taxonomy, links to related posts or episodes, and a call-to-action link, with a warning when a post has no code, formula, or measured number.Instagram posts: approved images go to your Instagram professional account as feed posts, converted to JPEG and staged on your R2 domain for Meta to fetch. A one-time login saves a never-expiring Page token in its own 0600 file. Carousels, Stories, and Reels are planned.
Content management: agents can list what's on Instagram, YouTube, dev.to, and Substack and remove one item you named at a time: delete an Instagram post, YouTube video, or Substack post or draft (permanent), or unpublish a dev.to article back to draft (dev.to's API can't delete). Each removal checks the item is yours first, has a dry run, and is logged with what was removed.
YouTube Shorts: uploads that are square or vertical and up to 3 minutes become Shorts; with
expect_short, the engine measures the clip first (ffprobe, rotation-aware) and refuses one that would land as a regular video.YouTube thumbnails and episode art: your agent renders the art; the engine sets the headline in your show's fonts and colors (auto-fitted, clear of the duration badge, under 2 MB) and pushes it to YouTube after approval. The same art and headline also become the episode's square icon in Apple Podcasts, Spotify, and other apps (2048 px, with your show's wordmark), published with the episode;
REQUIRE_EPISODE_IMAGE=truemakes it mandatory.Audience metrics: pluggable collectors (OP3 downloads, Cloudflare audio traffic, X, Instagram, and YouTube engagement for the show's own posts and videos, dev.to, Hashnode, and Substack reach for the blog posts the engine cross-posted, or your own) feed a local SQLite store, an offline HTML dashboard (an overview plus a tab per platform with every collected number, filtered by range or a stretch you drag across the timeline), and MCP tools agents can query.
Safety: see the list below; checks run before any upload.
Backups: incremental, to a private Hugging Face dataset.
What You Need
podcast_server doesn't host anything itself. It drives services you own. The pieces below are what a show needs; each links to its own setup docs, which are the authority for that service (and several have their own MCP server your agent can use for setup).
Required
Piece | What it's for | Get set up |
A domain | Your audio URLs (e.g. | Any registrar, e.g. Cloudflare Registrar. The domain's DNS must be on Cloudflare for the R2 custom domain (full setup). |
Cloudflare R2 bucket | Stores the MP3s and serves them (no egress fees, range requests) | R2 docs: create a bucket, an API token with Object Read & Write, and a custom domain on it. Cloudflare's MCP servers can help an agent do this. |
A home for the RSS feed | The URL podcast apps subscribe to | Either nothing extra ( |
Cover art | Required by every directory | Square JPEG/PNG, 1400–3000 px, at a public URL. See Apple's requirements. |
Directory listings | How listeners find the show | Submit your feed URL once to Apple Podcasts Connect, Spotify for Creators, and Podcast Index (which feeds many smaller apps). |
An MCP client and Python tooling | The agent that runs the tools, and the engine's runtime | Any MCP client (Claude Desktop, Cursor, ...), plus uv. |
Optional
Piece | Unlocks | Get set up |
Staging episodes straight from a Descript export (chapters from markers) | Export the transcript as Markdown; see ADOPTING. | |
X developer app + xurl |
| An app in the X developer portal (read and write, OAuth 2.0); X bills API use. Steps in ADOPTING. |
Instagram professional account (Business or Creator) + a Meta app |
| A Meta developer app; a never-expiring Page token for the Facebook Page linked to the account (or a Unified login token); your own account needs no App Review. Saved by |
dev.to API key |
| |
A Hashnode publication on Pro or Growth + the Hashnode CLI |
|
|
A Substack publication |
| Substack has no official publishing API: this uses the community python-substack library and your browser session cookie, which controls the whole account and expires. Steps in ADOPTING. For episodes, Substack's own Distribute to Substack reads your feed, no engine changes needed. |
YouTube Data + Analytics APIs |
| A Google Cloud OAuth client (Data API, Analytics API). Custom thumbnails need a phone-verified channel. |
An image model your agent can call | Thumbnail art (the engine only sets the text) | Whatever your agent supports (e.g. via its own MCP or API tools); put fonts and colors in |
Free, open download analytics (stats are public) |
| |
An IndexNow key | Deploys ask Bing, Yandex, and other engines to crawl changed pages ( | Any 8-128 letters, digits, or dashes as |
Cloudflare analytics token | Audio-traffic metrics from the edge | A token with Analytics Read on the zone (newer dashboards: a policy scoped to the Domain). |
Hugging Face account | Private, incremental backups of audio and catalog | A private dataset; Hugging Face also offers an MCP server. |
ADOPTING.md walks through each step in order with the exact settings.
Quick Start
# needs uv: https://docs.astral.sh/uv/ (curl -LsSf https://astral.sh/uv/install.sh | sh)
git clone <this repo> podcast_server && cd podcast_server
uv sync # creates .venv with Python 3.11+ and locked dependencies
cp .env.example .env && chmod 600 .env # fill in your show's values
uv run python -m core.doctor # verifies R2, domain, site, artwork, feed, and each optional integration
uv run python -m unittest discover -s testsADOPTING.md covers Cloudflare setup, configuration, first publish, and migration in detail.
Configuration
Every setting is documented inline in .env.example.
Group | Variables |
Show identity (required) |
|
Show identity (optional) |
|
Storage (required) |
|
Website |
|
Show data |
|
Publishing rules (optional) |
|
Integrations (optional) |
|
X posting (optional) |
|
Hashnode (optional) |
|
Instagram posting (optional) |
|
Blog cross-posting (optional) |
|
Metrics (optional) |
|
There are no show values in the code: startup fails and lists any required variable that's missing. PODCAST_SERVER_ENV_FILE=/path/to/show.env selects a different config (one per show).
Your Show's Private Data
Keep DATA_DIR outside this checkout, ideally in its own private repo. examples/show-data/ is a template to copy:
my-show-data/
├── PLAYBOOK.md # your editorial voice, title rules, workflows (agents read this first)
├── DEPLOYMENT.md # your infrastructure record: DNS, R2, website, backups, credential locations
├── templates/ # social_long.txt, social_short.txt, thumbnail_style.json, site_rules.json, crosspost_footer.md, fonts/
├── social/ # logs of public actions and removals (*_deletions.jsonl, devto_unpublished.jsonl): x_posts.jsonl, instagram_posts.jsonl, devto_posts.jsonl, substack_posts.jsonl, substack_newsletters.jsonl, youtube_uploads.jsonl, youtube_thumbnails.jsonl
├── newsletters/ # original Substack newsletter articles, <slug>.md (title, subtitle, tags frontmatter)
├── youtube_videos.json # optional: back-catalog videos → episodes, for YouTube metrics
├── thumbnails/ # thumbnail_art_templates/ (staged art), final_art/ (thumbnails, <slug>-substack.png previews), podcast_art/ (episode icons)
├── media/ # staged GIFs and images for newsletters and blog posts (podcast_make_gif)
├── excluded_episodes.json # episodes that must never be (re)published
├── transcripts/ # <slug>.txt
├── catalog.db # created on first run; don't commit it (back it up instead)
├── metrics.db # collected audience metrics; safe to delete and re-collect
└── metrics/dashboard.html # written by `python -m metrics.report`Register the MCP Server
{
"mcpServers": {
"podcast_server": { "command": "/absolute/path/to/podcast_server/bin/run-mcp.sh" }
}
}Agents should read AGENTS.md and then your PLAYBOOK.md.
MCP Tools
Area | Tools |
Getting oriented |
|
Catalog |
|
Publishing |
|
Content |
|
Distribution |
|
Content management |
|
Metrics |
|
Common Commands
Task | Command |
Check the setup |
|
Rebuild feed (+ pages), no deploy |
|
Import a back catalog |
|
Back up |
|
Collect metrics + write the dashboard |
|
Connect or reconnect Instagram (access token) |
|
Connect or reconnect Substack (session cookie) |
|
Run tests |
|
Safety Guarantees
The engine refuses to:
Reuse a slug or regenerate a GUID, which would show duplicate episodes on every subscriber's device.
Re-add excluded episodes: a database trigger blocks them, even for raw SQL.
Publish unrelated website work: deploys commit only generated files, only from
WEBSITE_BRANCH.Publish broken downloads: episodes whose audio isn't in R2 are left out of the feed and pages.
Upload arbitrary files to the public bucket, or overwrite existing (immutably cached) objects.
Leak credentials: downloads are https-only, the Descript token is sent only to Descript hosts, the dev.to key only to dev.to, the Hashnode login stays in the Hashnode CLI, the Substack session cookie and the Instagram token stay in their own 0600 files (the doctor fails if others can read them), the Instagram token is sent only to Meta, in a header, and a user token pasted at login is swapped for the Page token and never stored, and X and YouTube tokens stay in their own CLIs' or OAuth files.
Publish cross-posts you didn't ask for: Substack copies are always unpublished drafts (Substack never emails subscribers from the engine), dev.to and Hashnode copies are drafts unless
publish=true, and a blog post that already has a copy (logged, or found on the account) is never sent again.Ship a blog post below your standards: posts that miss their discovery brief or your
site_rules.jsonare refused when written and again when deployed, including posts written by hand.Upload local files to Substack: Substack drafts accept only https images, because the library would otherwise upload any image path found on disk.
Attach arbitrary files: X media, Instagram images, and YouTube thumbnails accept only image/video types within each platform's size and shape limits, checked before any upload.
Post to the wrong Instagram account or twice: a token saved for another account than
INSTAGRAM_USERNAMEis refused, and the same image with the same caption returns the logged post instead of a second one.Remove content in bulk or blindly: the delete and unpublish tools (Instagram, YouTube, dev.to, Substack) take one id per call, read the item first, refuse anything that isn't your account's own, and log what they removed. There is no delete-all tool.
Publish content nobody can find: episodes, blog posts, YouTube uploads, Instagram posts, and X media are checked against the content's discovery brief before anything goes public; skipping a check takes a
discovery_overridewith a reason, which is recorded. YouTube titles, descriptions, and tags over the platform's limits are refused rather than silently cut.Lose track of public actions: every X and Instagram post, YouTube upload, and thumbnail change is logged as soon as it succeeds, so an agent can check before retrying instead of posting twice.
Troubleshooting
Symptom | Cause and fix |
| The site repo isn't on |
| Git has no usable credentials. On headless Linux, keyring helpers (libsecret) can't unlock; use |
Rewritten show notes don't reach podcast apps | Edit them with |
Backup re-downloads audio every run | Catalog byte lengths don't match R2; sizes must come from the stored object (the importer's |
| Your resolver cached an old "no such host" answer; it clears on its own. |
Doctor says a metrics source is ready, but collection fails | The doctor checks settings, not live access. The run's message says what to fix, e.g. Cloudflare |
| The session cookie expired or you signed out of Substack. Run |
| A copy of that post is already there (logged, or found on the account). To make a fresh one, delete the old copy and remove the slug's line from |
Hashnode tools say | Hashnode's API only works for publications on Pro or Growth; upgrade under the blog's Billing. A "not logged in" error means run |
| The token expired or lost access (a password change or removed permission invalidates Page tokens; Unified login tokens follow their configuration's expiry). Get a new token as in ADOPTING and run |
| Instagram couldn't fetch the staged image from |
"No discovery brief for ''" or "Discovery check failed" | Save the approved brief with |
Transcripts don't show in Apple Podcasts | In Podcasts Connect, set the show to display transcripts you provide; Apple reads only |
YouTube upload result has | The video is live; only that step failed (often quota: a caption costs 400 units, a playlist entry 50). Add it by hand in YouTube Studio, or wait for the quota to reset. Don't re-upload. |
| Custom thumbnails aren't enabled for the channel; verify it in YouTube Studio (phone verification). |
Project Structure
podcast_server/
├── core/ # config, catalog (db), R2 storage, feed XML, site output + deploy, IndexNow pings, blog site rules, doctor and capabilities, discovery briefs and checks, episode transcript/chapters/art, thumbnail renderer, helpers
├── mcp_server/server.py # the MCP tools, their annotations, and the connection instructions
├── importers/ # rss.py (any host, GUID-preserving), descript.py (staging)
├── exporters/ # Astro pages, blog posts, social drafts, X and Instagram posting, dev.to, Hashnode, and Substack cross-posts, YouTube upload + thumbnails
├── metrics/ # collectors (OP3, Cloudflare, X, Instagram, YouTube, dev.to, Hashnode, Substack, plugins), store, analysis, dashboard (Chart.js in vendor/)
├── bin/ # run-mcp.sh (MCP launcher), collect-metrics.sh (scheduler entry)
├── scripts/backup_to_hf.py
├── examples/show-data/ # template for your private DATA_DIR
├── tests/
├── pyproject.toml / uv.lock # uv project: dependencies + lockfile
├── ADOPTING.md # run your own show
├── AGENTS.md # operating guide for agents
└── PLAN.md # architecture and roadmapLicense
Business Source License 1.1: free for personal, open-source, and internal business use; not for offering a competing commercial hosted podcast service. Converts to Apache 2.0 on October 26, 2029.
Built by Harpreet Sahota to run a real show, then made show-neutral so you can run yours.
Available Tools
12 toolsadd_tagsAdd TagsB
Add tags to a specific draft/post.
Inputs: tags (required), draft_id (required). Returns: object
get_draftGet DraftC
Get a specific draft by its ID.
Inputs: draft_id (required). Returns: object
get_statusGet StatusA
Get the authentication status and basic user information.
Inputs: no named parameters. Returns: object
list_draftsList DraftsC
List drafts for the current publication.
Inputs: limit, filter, offset. Returns: result
list_publicationsList PublicationsB
List all publications available to the authenticated user.
Inputs: no named parameters. Returns: result
post_draft_from_markdownPost Draft From MarkdownA
Create or update a Substack draft from Markdown.
This tool builds a Substack `Post` from markdown content and posts a draft.
It supports optional tag assignment, prepublish (setup check), and publishing.
Args:
title: Draft title.
markdown: Markdown body content.
subtitle: Optional subtitle text.
audience: One of `everyone`, `only_paid`, `founding`, `only_free`.
write_comment_permissions: One of `none`, `only_paid`, `everyone`.
search_engine_title: Optional title for search engine optimization.
search_engine_description: Optional description for search engine optimization.
slug: Optional URL slug for the post.
draft_section_id: Optional section ID for the draft.
tags: Tag or list of tags to attach to the post.
prepublish: If true, calls `prepublish_draft` after creation.
publish: If true, calls `publish_draft` after creation (and optionally prepublish).
send: Passed to `publish_draft` for newsletter delivery.
share_automatically: Passed to `publish_draft`.
Returns:
dict containing drafted post (`draft`), optional `tags`, `prepublish`, `publish` results.
Examples:
With the YAML structure from the README, a caller can map fields like:
```yaml
title: "My Post Title"
subtitle: "My Post Subtitle"
audience: "everyone"
write_comment_permissions: "everyone"
markdown: |
# Hello
This is the body.
tags:
- python
- substack
prepublish: true
publish: true
send: false
share_automatically: true
```
Then invoke via MCP directly:
```python
from substack_mcp.mcp_server import post_draft_from_markdown
result = await post_draft_from_markdown(
title='My Post Title',
markdown='# HelloThis is the body.', subtitle='My Post Subtitle', audience='everyone', write_comment_permissions='everyone', tags=['python', 'substack'], prepublish=True, publish=False, # set true when ready ) print(result) ```
A longer process with manual prepublish/publish calls:
```python
from substack_mcp.mcp_server import (
post_draft_from_markdown,
prepublish_draft,
publish_draft,
add_tags,
)
d = await post_draft_from_markdown(
title='Long flow',
markdown='Content',
tags=['a','b'],
publish=False,
)
draft_id = d['draft']['id']
await add_tags(draft_id, ['post-tag', 'news'])
await prepublish_draft(draft_id)
await publish_draft(draft_id, send=True, share_automatically=True)
```
This docstring example is meant to mirror the YAML-driven workflow and show how to decompose the same operations into explicit tool calls.
Inputs: title (required), markdown (required), send, slug, +10 more. Returns: object
prepublish_draftPrepublish DraftC
Invoke prepublish checks for a draft.
Inputs: draft_id (required). Returns: object
publish_draftPublish DraftA
Publish a draft to live post state. (Legacy compatibility interface).
This tool remains for backward compatibility. It is recommended to use
publish_draft_checked instead, which provides a safer publishing path
with explicit confirmation and prepublish validation.
Inputs: draft_id (required), send, share_automatically. Returns: object
publish_draft_checkedPublish Draft CheckedB
A safer publishing path that requires confirmation and runs prepublish checks.
Inputs: draft_id (required), send, confirm, share_automatically. Returns: object
put_draftPut DraftC
Update an existing draft by draft ID.
Inputs: draft_id (required), update_payload (required). Returns: object
schedule_draftSchedule DraftC
Schedule a draft for release.
Inputs: at (required), draft_id (required). Returns: object
unschedule_draftUnschedule DraftC
Unschedule a previously scheduled draft.
Inputs: draft_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Several tools overlap: post_draft_from_markdown bundles create/update plus prepublish/publish/tags, duplicating add_tags, prepublish_draft, and publish_draft, and put_draft also updates drafts, muddying create-vs-update boundaries. publish_draft and publish_draft_checked are near-duplicates, though the descriptions explicitly flag the legacy/safer distinction. Descriptions help but an agent must still reason about which of several paths to use.
Most tools follow a clean verb_noun pattern (add_tags, prepublish_draft, publish_draft, get_status, list_drafts, get_draft, schedule_draft, unschedule_draft). Minor deviations: put_draft uses 'put' instead of 'update', and post_draft_from_markdown is a longer, less uniform form. Overall consistent and readable.
Twelve tools is well-scoped for a publishing workflow and each maps to a recognizable operation. Slight redundancy from the legacy publish_draft alongside publish_draft_checked, but count is reasonable.
Draft lifecycle is mostly covered (create, get, list, update, publish, schedule/unschedule, add tags), but there is no delete_draft and no way to remove tags. Publication listing exists without a corresponding get/select-publication operation, leaving a few dead ends.
Maintenance
Related MCP Connectors
Hosted MCP server for AI agents to post to LinkedIn profiles and X and upload to YouTube.
Personal podcast queue and private RSS feed managed through a bounded MCP tool set.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for self-hosted static site publishing on Cloudflare Workers. Enables AI coding agents to deploy pages with a single 'publish' tool and get live URLs, with support for atomic updates, versioning, and per-site passwords.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables self-hosted AI gateway and agent control plane with governed MCP tools, virtual-key budgets, caching, and audit, supporting OpenAI, Anthropic, Gemini, MCP, and A2A protocols. It provides deterministic prompt enhancement and governed execution with a zero-credential first run.10Apache 2.0
- AlicenseAqualityBmaintenanceAI podcast generator MCP server: your agent writes a two-host script, the server voices each line with cloned host voices and exports MP3, SRT transcript, chapters and RSS.11MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to publish HTML pages and their files to a personal, self-hosted Cloudflare Workers host over MCP, REST, or a CLI, with each artifact served from its own origin behind Cloudflare Access.MIT