# conorbronsdon/substack-mcp [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/conorbronsdon/substack-mcp  
**GitHub Stars:** 31  
**npm Downloads (last month):** 474  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/conorbronsdon-substack-mcp

## Description
MCP server for Substack — read posts, manage drafts, publish Notes, get comments, and upload images. Safe by design: cannot publish or delete posts.

## Tools
Capabilities this server exposes over MCP:

- **get_subscriber_count** — Get the current subscriber count for your Substack publication. Returns `precision`: 'exact' when the API reports a true count, 'approximate' when only Substack's rounded value is available (the real number is that or higher — render it hedged, e.g. '1,000+'), or 'unavailable' with count -1. Never treat an approximate value as exact.
- **list_published_posts** — List published posts with pagination. Returns title, date, slug, and URL for each post.
- **list_drafts** — List draft posts. Returns title, creation date, and audience for each draft.
- **get_post** — Get the full content of a published post by ID. Returns title, body HTML, metadata.
- **get_draft** — Get the full content of a draft post by ID. Returns title, body, metadata.
- **get_post_comments** — Get comments on a published post. Returns commenter name, comment body, date, and reaction counts.
- **get_sections** — List your publication's sections (categories). Returns each section's id and name. Use a section id as `section_id` when creating or updating a draft to file it under that section.
- **get_post_analytics** — Get performance stats (views, emails sent/delivered/opened, signups, subscribes, estimated value, comments, reactions) for a published post by ID. Substack has no per-post stats endpoint, so this searches your 500 most recent published posts for the ID; returns a not-found note if it isn't among them.
- **list_scheduled_posts** — List posts scheduled for future publication, soonest first. Read-only visibility into what's queued — scheduling itself is done in Substack's editor (this server does not schedule, publish, or delete long-form posts). Returns id, title, audience, and scheduled time (`trigger_at`).
- **create_draft** — Create a new draft post. Accepts markdown body which is converted to Substack's format. Does NOT publish — creates a draft only.
- **update_draft** — Update an existing draft post. Only works on unpublished drafts. Accepts markdown body.
- **upload_image** — Upload an image to Substack's CDN. Provide exactly one of `image_base64` (a base64 data URI) or `image_path` (a local file path). Returns a hosted image URL that is publicly fetchable by anyone with the link (an unlisted asset — not attributed to you or added to your feed).
- **create_note** — Create a Substack Note (short-form content). Accepts markdown text. PUBLISHES IMMEDIATELY to your public Notes feed — Notes have no draft state on Substack, and this server has no delete tools, so there is no undo from here.
- **create_note_with_link** — Create a Substack Note with a link attachment, displayed as a rich card below the note text. PUBLISHES IMMEDIATELY to your public Notes feed — same caveats as create_note: no draft state, no undo from this server.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "substack-mcp": {
    "command": "npx",
    "args": ["-y","@conorbronsdon/substack-mcp"],
    "env": {
      "SUBSTACK_PUBLICATION_URL": "",
      "SUBSTACK_SESSION_TOKEN": "",
      "SUBSTACK_USER_ID": "",
      "SUBSTACK_MCP_HOME": ""
    }
  }
}
```

**Requires environment variables:** `SUBSTACK_PUBLICATION_URL`, `SUBSTACK_SESSION_TOKEN`, `SUBSTACK_USER_ID`, `SUBSTACK_MCP_HOME` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What conorbronsdon/substack-mcp MCP server does

The conorbronsdon/substack-mcp MCP server connects an MCP-compatible AI client to a Substack publication. Its read operations cover published posts, drafts, comments, sections, scheduled posts, subscriber counts, and post-level analytics. Full post and draft content includes fields such as title, body, and metadata, while list operations provide publication records with pagination where supported.

Long-form content changes remain draft-only. An agent can create a new draft from Markdown or update an unpublished draft, but it cannot publish, delete, or schedule a long-form post. Scheduling remains an action performed in Substack’s editor. The server can read posts already scheduled there with their IDs, titles, audiences, and scheduled times.

The exception is Substack Notes. `create_note` and `create_note_with_link` publish short-form content directly to the public Notes feed because Substack does not provide a draft state for Notes. These operations have no preview or undo through the server.

## How it works

The server communicates with Substack using publication credentials supplied through environment variables or a locally stored browser-login session. Requests are scoped to a publication, and the configuration can support more than one publication by defining a separate URL, session token, and user ID triplet for each one.

Post analytics require a lookup rather than a dedicated per-post statistics endpoint. The server searches the 500 most recent published posts for the requested ID and reports a not-found result when the post is outside that range. Subscriber results include a precision indicator: exact, approximate, or unavailable. Approximate values should be displayed as lower-bound-style figures such as “1,000+,” not as exact counts.

Image uploads accept either a base64 data URI or a local file path, but not both. The returned Substack CDN URL is publicly fetchable by anyone with the link, although the asset is unlisted and is not attributed to the publication feed.

## Setup and configuration

The conorbronsdon/substack-mcp MCP server is available from npm as `@conorbronsdon/substack-mcp`. A client can run it with `npx -y @conorbronsdon/substack-mcp` and provide `SUBSTACK_PUBLICATION_URL`, `SUBSTACK_SESSION_TOKEN`, and `SUBSTACK_USER_ID` in the MCP server environment.

As an alternative, the optional login command opens Chromium through Playwright, captures the Substack session cookie, resolves the user ID, and stores an encrypted session file under `~/.substack-mcp/session.json`. `SUBSTACK_MCP_HOME` can change that directory. Playwright must be installed separately. When the stored session is available and the credential environment variables are unset, the MCP server reads the session file automatically.

Claude Desktop configuration uses a server entry with the npm runner and those environment variables. The repository also documents Claude Code configuration. Browser login storage is machine-bound and encrypted, but it is not a substitute for a secret vault.

## Tools and capabilities

The available operations include:

- Count publication subscribers with an explicit precision status.
- List and retrieve published posts and drafts.
- Read post comments, sections, scheduled posts, and performance statistics.
- Create or revise unpublished drafts from Markdown.
- Upload an image and receive a hosted CDN URL.
- Publish a Note immediately, optionally with a link card.

The tools declare read-only and non-destructive annotations where applicable, but tool annotations are hints. The tool descriptions and the actual behavior are authoritative, especially for Note publishing and public image URLs.

## Limitations and notes

The conorbronsdon/substack-mcp MCP server does not provide long-form publishing, deletion, or scheduling controls. Draft updates only work for unpublished drafts. Notes are public immediately and cannot be reverted through this server. Uploaded images are publicly retrievable by URL, so agents should avoid treating them as private files. A copied browser session file is protected against casual inspection and use on another machine, but code running under the same operating-system account may still be able to re-derive its key.

_Full upstream README: https://allmcps.com/mcp/conorbronsdon-substack-mcp/readme_