Skip to content
Back to search

substack-mcp

A Model Context Protocol (MCP) Server for Substack enabling LLM clients to interact with Substack's API for automations like creating posts, managing drafts, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marcomoauro--substack-mcp/badge.svg)](/listings/marcomoauro--substack-mcp)

HTML

<a href="/listings/marcomoauro--substack-mcp"><img src="/api/listings/marcomoauro--substack-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The fastest installation uses [Node.js 22 or newer](https://nodejs.org/) and `npx`.

1. Collect your Substack credentials

Sign in to Substack in your browser and open your publication dashboard. You need three values:

- **Publication URL** — the full base URL of your publication, for example `https://your-publication.substack.com`. - **Session token** — open your browser's developer tools, select **Network**, filter to **Fetch/XHR**, and reload the dashboard. Open a successful authenticated request to your publication. Under **Request Headers**, find the `Cookie` header and locate a session cookie named `substack.sid` or `connect.sid`. Copy its value without the cookie name or the rest of the header. If both names appear with different values, test them separately and locally with the read-only verification in step 3; never paste either value into an issue. - **User ID** — in the same Network panel, search for a successful `publication_user` request. In its JSON response, copy the numeric `id` inside the `user` object.

If the browser UI differs, the illustrated [credential guide](https://implementing.substack.com/p/mcp-server-for-substack) shows the same requests. If authentication later stops working, sign in again and repeat these steps to obtain the current token.

2. Add the server to your MCP client

For clients that accept MCP JSON configuration, add:

{
  "mcpServers": {
    "substack": {
      "command": "npx",
      "args": ["-y", "substack-mcp@latest"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com",
        "SUBSTACK_SESSION_TOKEN": "your-session-token",
        "SUBSTACK_USER_ID": "your-user-id"
      }
    }
  }
}

Replace the three example values, save the configuration, and restart your MCP client. Consult your client's documentation if it uses a different configuration format.

3. Verify the connection

Ask your client:

> List my five most recent Substack drafts.

The client should call `list_posts` with `status: "drafts"`. If it fails, check the client's MCP logs and the [logging section](#-logs) below before opening an issue.

Docker quick start

To use the published Docker image instead of Node.js, add this server configuration:

{
  "mcpServers": {
    "substack": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SUBSTACK_PUBLICATION_URL",
        "-e", "SUBSTACK_SESSION_TOKEN",
        "-e", "SUBSTACK_USER_ID",
        "marcomoauro/substack-mcp:latest"
      ],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com",
        "SUBSTACK_SESSION_TOKEN": "your-session-token",
        "SUBSTACK_USER_ID": "your-user-id"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 709 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Substack MCP Server
  2. A Model Context Protocol (MCP) Server for [Substack](https://substack.com) enabling LLM clients to interact with Substack's API for automations like creating posts, managing drafts, and more.
  3. [![Docker Pulls](https://img.shields.io/docker/pulls/marcomoauro/substack-mcp.svg)](https://hub.docker.com/r/marcomoauro/substack-mcp)
  4. [![npm downloads](https://img.shields.io/npm/dm/substack-mcp.svg)](https://www.npmjs.com/package/substack-mcp)
  5. Create and publish posts, work with subscribers and analytics, browse your reader feeds, manage
  6. tags and comments, and upload images — 27 tools exposed through one MCP server.
  7. > [!IMPORTANT]
  8. > Substack does not provide a public API for these operations. This server uses your authenticated
  9. > web session. Treat the session token exactly like a password: keep it local, never commit it, and
  10. > never include it or a complete Cookie header in a bug report.
  11. ## Quick start
  12. The fastest installation uses [Node.js 22 or newer](https://nodejs.org/) and `npx`.
  13. ### 1. Collect your Substack credentials
  14. Sign in to Substack in your browser and open your publication dashboard. You need three values:
  15. - **Publication URL** — the full base URL of your publication, for example
  16. `https://your-publication.substack.com`.
  17. - **Session token** — open your browser's developer tools, select **Network**, filter to
  18. **Fetch/XHR**, and reload the dashboard. Open a successful authenticated request to your
  19. publication. Under **Request Headers**, find the `Cookie` header and locate a session cookie named
  20. `substack.sid` or `connect.sid`. Copy its value without the cookie name or the rest of the header.
  21. If both names appear with different values, test them separately and locally with the read-only
  22. verification in step 3; never paste either value into an issue.
  23. - **User ID** — in the same Network panel, search for a successful `publication_user` request. In
  24. its JSON response, copy the numeric `id` inside the `user` object.
  25. If the browser UI differs, the illustrated [credential guide](https://implementing.substack.com/p/mcp-server-for-substack)
  26. shows the same requests. If authentication later stops working, sign in again and repeat these steps
  27. to obtain the current token.
  28. ### 2. Add the server to your MCP client
  29. For clients that accept MCP JSON configuration, add:
  30. ```json
  31. {
  32. "mcpServers": {
  33. "substack": {
  34. "command": "npx",
  35. "args": ["-y", "substack-mcp@latest"],
  36. "env": {
  37. "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com",
  38. "SUBSTACK_SESSION_TOKEN": "your-session-token",
  39. "SUBSTACK_USER_ID": "your-user-id"
  40. }
  41. }
  42. }
  43. }
  44. ```
  45. Replace the three example values, save the configuration, and restart your MCP client. Consult your
  46. client's documentation if it uses a different configuration format.
  47. ### 3. Verify the connection
  48. Ask your client:
  49. > List my five most recent Substack drafts.
  50. The client should call `list_posts` with `status: "drafts"`. If it fails, check the client's MCP
  51. logs and the [logging section](#-logs) below before opening an issue.
  52. ### Docker quick start
  53. To use the published Docker image instead of Node.js, add this server configuration:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "substack": {
  58. "command": "docker",
  59. "args": [
  60. "run", "-i", "--rm",
  61. "-e", "SUBSTACK_PUBLICATION_URL",
  62. "-e", "SUBSTACK_SESSION_TOKEN",
  63. "-e", "SUBSTACK_USER_ID",
  64. "marcomoauro/substack-mcp:latest"
  65. ],
  66. "env": {
  67. "SUBSTACK_PUBLICATION_URL": "https://your-publication.substack.com",
  68. "SUBSTACK_SESSION_TOKEN": "your-session-token",
  69. "SUBSTACK_USER_ID": "your-user-id"
  70. }
  71. }
  72. }
  73. }
  74. ```
  75. ## 🛠 Available Tools
  76. <details>
  77. <summary><strong>create_draft_post</strong> - Create a draft post</summary>
  78. **Inputs**:
  79. - `title` (string): Title of the post
  80. - `subtitle` (string): Subtitle of the post
  81. - `body` (string): Body of the post. Plain text becomes one paragraph per line — **Markdown is not
  82. interpreted**, so `## Heading` arrives literally. A JSON string of a Substack document also works
  83. and is validated against the same schema `set_post_body` publishes, so an unrecognised node name
  84. is an error rather than a silently mangled post.
  85. **Returns**: `{draft_id, is_published}`. Pass `draft_id` to `get_draft` to read the draft back.
  86. For anything structured — headings, lists, links, code, images, a paywall — use `set_post_body`
  87. after creating the draft: the schema is published there, so the calling model can read the node
  88. vocabulary rather than guess at it.
  89. </details>
  90. <details>
  91. <summary><strong>list_subscribers</strong> - List and filter your subscribers</summary>
  92. Exposes the same filtering the Subscribers dashboard offers: 48 columns, 18 operators, free-text
  93. search, sorting and pagination.
  94. **Inputs**:
  95. - `filters` (array, optional): conditions combined with **AND**, each `{column, operator, value}`
  96. - `search` (string, optional): free text matched against subscriber name and email
  97. - `sort_by` (string, optional): any filterable column
  98. - `sort_direction` (`asc` | `desc`, optional): defaults to `desc`
  99. - `limit` (number, optional): 1–100, defaults to 25
  100. - `offset` (number, optional): for paging
  101. Which operators a column accepts depends on its type:
  102. | Type | Operators |
  103. |---|---|
  104. | `Int` | `is` `is_not` `gt` `gte` `lt` `lte` |
  105. | `String` | `is` `is_not` `is_any_of` `contains` `starts_with` `ends_with` `includes_none` |
  106. | `DateTime` | `is_on` `is_after` `is_on_or_after` `is_before` `is_on_or_before` |
  107. | `Array` (`tag_ids`, `emails_enabled`) | `includes_any` `includes_all` `includes_none` |
  108. | `subscription_type`, `group_membership` | `is` `is_not` `is_any_of` |
  109. The columns cover subscriber identity (name, email, country, state, group membership),
  110. subscription (type, start/expiry/cancel dates, revenue, Stripe plan, attribution), email
  111. engagement (opens and unique opens over 7d/30d/6mo, links clicked, sections) and site engagement
  112. (post views, unique posts seen, comments, shares, days active, activity rating). The full list
  113. with types reaches the client in the tool's JSON Schema, so a model does not have to guess names.
  114. **Returns**: `{count, returned, limit, offset, subscribers}`. `count` is the total matching the
  115. filters regardless of `limit`, so a call with `limit: 1` is a cheap way to size a segment.
  116. > **Note**: engagement columns can be *filtered* on here but are not part of the records this tool
  117. > returns — Substack takes the fields it returns from the publication's saved Display settings and
  118. > ignores a per-request column list. Use **`export_subscribers`** to read their values.
  119. There is no OR and no nesting: anything needing OR has to be issued as separate calls.
  120. </details>
  121. <details>
  122. <summary><strong>export_subscribers</strong> - Export subscribers with every column value</summary>
  123. The way to actually *read* the engagement metrics `list_subscribers` can only filter on: email opens
  124. over 7d/30d/6mo, unique emails seen, post views, unique posts seen, comments, shares, links clicked,
  125. days active and activity rating.
  126. **Inputs**:
  127. - `filters` (array, optional): the same conditions as `list_subscribers`, combined with AND
  128. - `search` (string, optional): free text matched against subscriber name and email
  129. - `columns` (array, optional): which columns to include, defaulting to **all** of them
  130. - `max_wait_seconds` (number, optional): 1–600, defaulting to 120
  131. **Returns**: `{count, columns, missing_columns, unmapped_columns, export_id, subscribers}`, where
  132. each subscriber is keyed by column name.
  133. Substack generates the file asynchronously, so the tool creates a subscriber set, requests the
  134. export, polls until it is ready and downloads it. A small export lands in a few seconds. If the wait
  135. budget runs out the tool says so and names the `export_id` rather than blocking.
  136. > **Two caveats**, both verified against the live API:
  137. > - `tag_ids` and `group_membership` **cannot** be exported. Substack drops them silently rather
  138. > than failing, so they are reported in `missing_columns` — asking for all 48 columns returns 46.
  139. > - Values arrive **display-formatted**, not raw: revenue is `"€50.00"` here and the number `50`
  140. > through `list_subscribers`. Dates are ISO strings.
  141. There is no paging: an export covers the whole matching set.
  142. </details>
  143. <details>
  144. <summary><strong>list_posts</strong> - List drafts, published or scheduled posts</summary>
  145. **Inputs**:
  146. - `status` (`drafts` | `published` | `scheduled`): which list to read
  147. - `search` (string, optional): free text matched against title and content
  148. - `limit` (number, optional): 1–100, defaults to 25
  149. - `offset` (number, optional): for paging
  150. - `sort_direction` (`asc` | `desc`, optional): drafts and published posts are newest-first,
  151. scheduled posts soonest-first
  152. **Returns**: `{status, total, returned, limit, offset, posts}`, each post summarised — use
  153. `get_draft` for the full content of an unpublished one.
  154. </details>
  155. <details>
  156. <summary><strong>get_draft</strong> - Read one draft in full</summary>
  157. **Inputs**:
  158. - `draft_id` (number): the id returned by `list_posts` or `create_draft_post`
  159. **Returns**: the draft as Substack stores it, body and audience/email settings included.
  160. </details>
  161. <details>
  162. <summary><strong>set_post_body</strong> - Replace a draft's body with a structured document</summary>
  163. The only way to write structured content: headings, lists, links, code blocks, quotes, images,
  164. buttons and a paywall. `create_draft_post` takes plain text; this takes the document Substack
  165. actually stores, and its schema is published in `tools/list` so the calling model can read the node
  166. vocabulary instead of guessing.
  167. **Inputs**:
  168. - `draft_id` (number): the id returned by `list_posts` or `create_draft_post`
  169. - `body` (object): a Substack ProseMirror document — `{type: 'doc', content: [...]}`
  170. Fifteen node types are accepted: `paragraph`, `heading`, `bullet_list`, `ordered_list`, `list_item`,
  171. `blockquote`, `highlighted_code_block`, `code_block`, `horizontal_rule`, `captionedImage`, `button`,
  172. `paywall`, `youtube2`, plus `digestPostEmbed`, `substack_mentions` and `directMessage` passed through
  173. unchanged so a document read with `get_draft` can be written back. Marks: `strong`, `em`, `code`,
  174. `strikethrough`, `link`.
  175. **Returns**: `{draft_id, nodes}`, where `nodes` counts what was stored by type — so a caller that
  176. asked for a paywall can confirm there is one. Validation cannot report a node that was never sent.
  177. Three things worth knowing:
  178. - **An image must already be hosted by Substack.** `image2.src` pointing at an external URL is
  179. stored but does not render. Use `upload_image` to re-host one and get a `src` that works.
  180. - **A document may contain at most one `paywall`.** Substack accepts two and renders both, leaving
  181. it undefined which one cuts the post, so this tool refuses the second.
  182. - **`ordered_list` numbers from `attrs.order`, not `attrs.start`.** A list given only `start`
  183. renders from 1 with no error.
  184. </details>
  185. <details>
  186. <summary><strong>upload_image</strong> - Host an image on Substack, from a URL or a local file</summary>
  187. Substack's editor uploads images as base64 data URIs to `POST /api/v1/image`, which answers with a
  188. Substack-hosted URL. `image2.src` in `set_post_body` and `cover_image` in `update_draft` only render
  189. such a URL, so this tool is the bridge. Substack itself only re-fetches URLs already in its own
  190. storage, so the image is encoded here rather than being handed off.
  191. **Inputs** — exactly one of `url` or `path`:
  192. - `url` (string): the http(s) URL of an image to download and re-host
  193. - `path` (string): absolute path to an image file on the machine running this server, read straight
  194. from disk with no download
  195. - `post_id` (number, optional): the post the image belongs to; its effect is unconfirmed
  196. **Returns**: `{id, url, content_type, bytes, width, height}` — put `url` into an `image2.src` when
  197. calling `set_post_body`, or into `cover_image` when calling `update_draft`.
  198. A **download** is guarded: only `http`/`https`, private and loopback hosts are refused after DNS
  199. resolution (redirects are re-checked at every hop), the content type must be an image, HEIC is
  200. rejected with a note to convert it, and the image may not exceed 10 MB.
  201. A **local file** is guarded differently, because it has no `Content-Type` header to trust. The path
  202. must be absolute — a relative one would resolve against this server's working directory, not the
  203. calling client's — and the type is read from the file's magic bytes rather than its extension, so a
  204. non-image with an image extension is caught here instead of at Substack. PNG, JPEG, GIF and WebP are
  205. accepted; HEIC and SVG are not. The same 10 MB cap applies, checked against the file size before the
  206. file is read. Note that `path` reads whatever absolute path it is given: if that matters in your
  207. setup, do not expose this server to a client you would not trust with your filesystem.
  208. </details>
  209. <details>
  210. <summary><strong>update_draft</strong> - Change a draft's title, subtitle or any of its Post settings</summary>
  211. The update is **partial**: only the fields you pass change, and the body is left alone.
  212. **Inputs**:
  213. - `draft_id` (number): the id returned by `list_posts` or `create_draft_post`
  214. - `draft_title` (string, optional)
  215. - `draft_subtitle` (string, optional)
  216. - `audience` (`everyone` | `only_paid` | `only_free` | `founding`, optional)
  217. - `write_comment_permissions` (`everyone` | `subscribers` | `only_paid` | `none`, optional): who may comment
  218. - `default_comment_sort` (`best_first` | `most_recent_first` | `oldest_first`, optional)
  219. - `cover_image` (string, optional): the social preview image. A URL already on `substack-post-media.s3.amazonaws.com` or `substackcdn.com` is used as-is; anything else is downloaded and re-hosted on Substack first, under the same guards as `upload_image`
  220. - `social_title` (string, optional): the title used when the post is shared elsewhere
  221. - `description` (string, optional): the social preview description — *not* the subtitle
  222. - `search_engine_title` (string, optional)
  223. - `search_engine_description` (string, optional)
  224. - `slug` (string, optional): the post's URL slug
  225. **Returns**: `{draft_id, updated_fields, draft_title, draft_subtitle, audience, is_published, cover_image, cover_image_rehosted_from}`.
  226. A call with no field to change is refused rather than sent as a no-op. `cover_image` is the URL that
  227. actually landed, which differs from the one passed when it was re-hosted.
  228. </details>
  229. <details>
  230. <summary><strong>publish_draft</strong> - Publish a draft</summary>
  231. **Inputs**:
  232. - `draft_id` (number): the id returned by `list_posts` or `create_draft_post`
  233. - `send` (boolean, optional): email the post to subscribers. **Defaults to `false`**, unlike the
  234. Substack API's own default — the post goes live on the web either way, but an email cannot be
  235. recalled, so it has to be asked for explicitly.
  236. **Returns**: `{status, draft_id, post_id, title, slug, canonical_url, emailed, email_sent_at}`.
  237. `emailed` is what was *asked* for; `email_sent_at` is the server's own record of whether it mailed.
  238. The email intent is written to the draft's `should_send_email` **before** publishing, as well as being
  239. passed on the publish call. That field is where the dashboard keeps the decision and it defaults to
  240. `true`, so setting only one of the two would risk mailing the whole list if the endpoint reads the
  241. draft rather than the request body.
  242. There is no unpublish tool: publishing cannot be undone from this server.
  243. </details>
  244. <details>
  245. <summary><strong>delete_draft</strong> - Delete an unpublished draft</summary>
  246. **Inputs**:
  247. - `draft_id` (number): the id returned by `list_posts` or `create_draft_post`
  248. **Returns**: `{status, draft_id, draft_title}`.
  249. Substack deletes drafts and published posts through the *same* endpoint, so this tool reads the
  250. target first and **refuses if it is published** — removing a live post is irreversible and is left
  251. to the dashboard.
  252. </details>
  253. <details>
  254. <summary><strong>get_publication</strong> - Read your publication's settings</summary>
  255. **Inputs**:
  256. - `full` (boolean, optional): return all 111 fields (~24 KB) instead of the projection.
  257. Defaults to `false`.
  258. **Returns**: by default a projection — name, subdomain, custom domain, hero text, copyright, sender
  259. name, logo, plans, payment state and the community/podcast flags — plus `_meta` naming how many
  260. fields were dropped. The full payload is mostly notification toggles and the raw HTML of the welcome
  261. email, terms and privacy pages.
  262. </details>
  263. <details>
  264. <summary><strong>get_user_profile</strong> - Read the account behind the session</summary>
  265. **Inputs**:
  266. - `full` (boolean, optional): include the complete `subscriptions` array. Defaults to `false`.
  267. **Returns**: `{id, name, handle, bio, photo_url, publications, primary_publication_id,
  268. subscription_count}`. `publications` lists every publication the session has a role on, which is how
  269. to discover that `SUBSTACK_PUBLICATION_URL` is not the only one it could be pointed at.
  270. </details>
  271. <details>
  272. <summary><strong>list_publication_tags</strong> - List the tags defined on your publication</summary>
  273. **Inputs**:
  274. - `include_hidden` (boolean, optional): include tags not shown in the navigation. Defaults to `true`.
  275. **Returns**: `{total, returned, tags}`, each `{id, name, slug, hidden}`. Tag ids are **UUIDs**, not
  276. integers — unlike every other id in this API.
  277. </details>
  278. <details>
  279. <summary><strong>get_post_tags</strong> - List the tags on one post</summary>
  280. **Inputs**:
  281. - `post_id` (number): the id from `list_posts`. Works for drafts too.
  282. **Returns**: `{post_id, count, tags}`, each `{post_tag_id, name, slug, hidden, association_id}`.
  283. The underlying endpoint answers only UUIDs, so this resolves the names against the publication's tag
  284. list. Neither `get_draft` nor `list_posts` carries tags, so this is the only way to read them back.
  285. </details>
  286. <details>
  287. <summary><strong>add_tag_to_post</strong> - Tag a post</summary>
  288. **Inputs**:
  289. - `post_id` (number): the id from `list_posts`. Works for drafts too.
  290. - `tag_name` (string): matched case-insensitively against existing tags
  291. - `create_if_missing` (boolean, optional): create the tag when no name matches. Defaults to `true`;
  292. set it to `false` to have a typo reported instead of turned into a new tag.
  293. **Returns**: `{status, post_id, tag, tag_created, association_id}` where `status` is `tagged` or
  294. `already_tagged` — re-adding a tag the post already has answers a bare `400` upstream, so it is
  295. checked first.
  296. Takes a name rather than an id because the ids are UUIDs, which no caller could reasonably hold.
  297. </details>
  298. <details>
  299. <summary><strong>get_post_comments</strong> - Read the comments on one of your posts</summary>
  300. **Inputs**:
  301. - `post_id` (number): the id from `list_posts`
  302. - `limit` (number, optional): 1–100, defaults to 50
  303. **Returns**: `{post_id, returned, automod_hidden_count, comments}`. Each comment carries its author,
  304. plain-text body, reaction and reply counts, and its position in the thread (`parent_comment_id`,
  305. `depth`). Comments withheld by Substack's automod are **counted, not merged in** — they arrive in a
  306. separate array upstream, and dropping them silently would turn "held" into "nobody commented".
  307. </details>
  308. <details>
  309. <summary><strong>comment_on_post</strong> - Comment on one of your posts</summary>
  310. **Inputs**:
  311. - `post_id` (number): the id from `list_posts`
  312. - `body` (string): plain text; Substack converts it server-side
  313. **Returns**: `{status, post_id, comment}`.
  314. This is published under your name. The full text is logged at `info` before the request, since the log
  315. is the only record of what was said. This server does not expose deletion, but the comment can be
  316. removed from the Substack UI — unlike a restack, a comment does have an id of its own.
  317. </details>
  318. The seven tools below read **`substack.com`**, not your publication. They are about the account as a
  319. *reader* — what it subscribes to, what is in its inbox and feed — which is a different host and a
  320. different id space from the publisher surface above.
  321. <details>
  322. <summary><strong>list_subscriptions</strong> - List what this account subscribes to</summary>
  323. **Inputs**:
  324. - `limit` (number, optional): 1–500, defaults to 100
  325. - `active_only` (boolean, optional): exclude paused and expired subscriptions. Defaults to `true`.
  326. **Returns**: `{returned, pages_fetched, subscriptions}`, each with plan, `membership_state`,
  327. `is_founding`, `is_favorite` and whether emails are off. Pages internally up to 20 requests and says
  328. `truncated: true` if that bound is what stopped it.
  329. Not to be confused with `list_subscribers`, which is who subscribes to *you*.
  330. </details>
  331. <details>
  332. <summary><strong>list_reader_posts</strong> - The reader Inbox</summary>
  333. **Inputs**:
  334. - `limit` (number, optional): 1–100, defaults to 20
  335. - `after` (string, optional): the `next_after` from a previous response. A **timestamp**, not an
  336. opaque cursor — this endpoint's own `cursor` field is always null.
  337. **Returns**: `{returned, more, next_after, posts}`, each post summarised with its reading state
  338. (`is_read`, `read_progress`, `is_saved`). The Inbox sends every post's full body; it is dropped here,
  339. so use `get_reader_post` to read one.
  340. </details>
  341. <details>
  342. <summary><strong>get_reader_post</strong> - Read any post in full</summary>
  343. **Inputs**:
  344. - `post_id` (number): from `list_reader_posts` or `get_reader_feed`
  345. - `include_body` (boolean, optional): defaults to `true`
  346. **Returns**: the post's metadata plus `body_html`. `body_truncated: true` means the body was withheld
  347. behind a paywall this session does not clear — `preview_text` still carries the teaser.
  348. The body stays HTML: converting it would mean a new dependency or a regex pass over markup, and a
  349. regex HTML converter mangles nested lists and embeds *silently*.
  350. </details>
  351. <details>
  352. <summary><strong>get_reader_feed</strong> - The Notes feed</summary>
  353. **Inputs**:
  354. - `tab` (string, optional): tab **id** — `for-you` (default) or `subscribed`. Never the display name:
  355. those are localized.
  356. - `limit` (number, optional): 1–50, defaults to 20
  357. - `cursor` (string, optional): the `next_cursor` from a previous response
  358. - `include_tabs` (boolean, optional): also return the available tab ids
  359. **Returns**: `{tab, returned, next_cursor, items}`. Each item is a `note` or a `post`.
  360. `non_content_items_skipped` counts the "people to follow" blocks Substack mixes into the array, which
  361. carry no content at all.
  362. </details>
  363. <details>
  364. <summary><strong>get_profile_feed</strong> - What one account has published</summary>
  365. **Inputs**:
  366. - `user_id` (number, optional): defaults to `SUBSTACK_USER_ID` — your own account
  367. - `type` (`all` | `notes` | `posts`, optional): defaults to `all`
  368. - `limit` (number, optional): 1–50, defaults to 20
  369. - `cursor` (string, optional)
  370. **Returns**: `{user_id, type, returned, next_cursor, items}`. When filtering, `read_from_profile`
  371. reports how many entries the page actually held — otherwise "3 notes out of 20 entries read" would
  372. look like "this account has written 3 notes".
  373. </details>
  374. <details>
  375. <summary><strong>get_comment_thread</strong> - Read a Note and its replies</summary>
  376. **Inputs**:
  377. - `comment_id` (number): without the `c-` prefix Substack uses in urls
  378. - `include_replies` (boolean, optional): defaults to `true`
  379. **Returns**: `{comment, branch_count, replies_returned, more_branches, next_cursor, branches}`. Each
  380. branch is a direct reply plus its descendants, with `parent_comment_id` and `depth` resolved.
  381. </details>
  382. <details>
  383. <summary><strong>restack_item</strong> - Restack a Note</summary>
  384. **Inputs**:
  385. - `comment_id` (number): the Note to restack, from `get_reader_feed` or `get_profile_feed`
  386. - `tab_id` (string, optional): defaults to `for-you`
  387. **Returns**: `{status, comment_id, restack_id, note}`.
  388. This is public and appears on your profile, and **cannot be undone from here**: a restack has no id of
  389. its own — it surfaces the original Note with `context: comment_restack` — so there is nothing for this
  390. server to delete. Remove it from the Substack UI.
  391. Notes only. Restacking a *post* is not offered: that call answers `404` even for a published post on
  392. your own publication, so a `post_id` parameter would produce an error that reads as the post being
  393. gone rather than as the tool being wrong.
  394. </details>
  395. <details>
  396. <summary><strong>get_publication_stats</strong> - Read the headline stats</summary>
  397. **Inputs**: none.
  398. **Returns**: total and recent subscribers, email and app subscribers, ARR, site views and the
  399. 30-day email open rate, each with its change where Substack reports one. If one of the underlying
  400. endpoints fails the rest are still returned, and the failure is named under `errors`.
  401. For anything deeper, use `get_analytics`.
  402. </details>
  403. <details>
  404. <summary><strong>get_post_stats</strong> - Rank your posts by any of 43 metrics</summary>
  405. Which post actually grew the list, which was worth most, which cost you subscribers. The dashboard's
  406. "Posts" tab, sortable and paged.
  407. **Inputs**:
  408. - `order_by` (string, optional): any of the 43 metrics, defaulting to `post_date`
  409. - `order_direction` (`asc` | `desc`, optional): defaults to `desc`
  410. - `limit` (number, optional): 1–100, defaults to 25
  411. - `offset` (number, optional): for paging the archive
  412. The metrics worth reaching for:
  413. | group | fields |
  414. |---|---|
  415. | conversion | `signups` `subscribes` `founding_subscribes` `annual_subscribes` `monthly_subscribes` `free_trials` `free_to_paid_upgrades` `signups_within_1_day` `estimated_value` |
  416. | churn | `unsubscribes` |
  417. | reading | `opens` `open_rate` `clicks` `click_through_rate` `views` `subscribers_finished_post` |
  418. | social | `likes` `shares` `restacks` `engagement_rate` `unique_engagements` |
  419. | delivery | `queued` `sent` `delivered` `dropped` |
  420. | video / podcast | `video_views` `video_minutes_watched` `downloads` `downloads_day30` … |
  421. **Returns**: `{total, returned, limit, offset, order_by, order_direction, posts}`. `total` is the
  422. whole archive, not the page; `order_by` and `order_direction` are echoed so a ranking is never read
  423. without knowing what produced it.
  424. > **Two caveats**, both verified:
  425. > - **There is no date filter.** `from_date`/`to_date` are ignored by this endpoint — `total` does not
  426. > change — so the schema does not offer them. Narrow by sorting and paging instead.
  427. > - Ranking by a **rate** (`open_rate`, `engagement_rate`, `click_through_rate`) descending puts posts
  428. > with no data first, because `null` sorts before numbers. The tool does not filter them out, since
  429. > that would silently answer a different question.
  430. >
  431. > `order_by` is an enum on purpose: the API answers `200` for a field it does not recognise and
  432. > returns an arbitrary order, so a typo would produce a ranking that looks authoritative.
  433. </details>
  434. <details>
  435. <summary><strong>get_analytics</strong> - Read one of 16 publication-level reports</summary>
  436. Everything behind the dashboard's Stats tabs, as one tool with a `report` enum rather than
  437. seventeen near-identical tools.
  438. **Inputs**:
  439. - `report` (string): which report to read — see the table below
  440. - `from_date`, `to_date` (string, optional): `YYYY-MM-DD`. Used only by the reports covering a
  441. period, which default to the last 30 days
  442. - `limit` (number, optional): 1–100, used only by `audience_overlap` and `subscriber_notes`
  443. | report | what it tells you |
  444. |---|---|
  445. | `retention` | cohort retention — how much of each signup cohort is still subscribed months later |
  446. | `retention_summary` | headline retention at 1, 6 and 12 months |
  447. | `unsubscribes` / `unsubscribes_timeseries` | churn, with the reasons given |
  448. | `growth_sources` | where new subscribers came from, ranked |
  449. | `growth_events` | the individual growth events in a window |
  450. | `referrals_leaderboard` / `referrals_summary` | who refers most; gifts sent, accepted, converted |
  451. | `audience_overlap` | other Substacks whose audience overlaps yours — the collaboration shortlist |
  452. | `audience_locations` | how many countries and US states your subscribers span |
  453. | `subscriber_notes` | recent Notes written by your subscribers |
  454. | `paid_subscriber_growth` | paid growth rate, new subscriptions, expirations |
  455. | `subscribers_timeseries`, `followers_timeseries`, `arr_timeseries` | counts and revenue over time |
  456. | `network_attribution` | what share of subscribers arrived via the Substack network |
  457. **Returns**: `{report, params, ignored_params, data}`. `params` is what was actually sent, defaults
  458. included — the same report answers very differently over a different window, so the numbers mean
  459. little without it. `ignored_params` names anything you passed that the chosen report does not
  460. accept, rather than dropping it silently.
  461. > Two neighbouring endpoints are deliberately **not** exposed: `audience_insights/location` (the
  462. > subscriber map) and `visitor_sources` answer `400` even for Substack's own dashboard, so they are
  463. > broken upstream rather than mis-called.
  464. </details>
  465. ## 🏗 Running from Source
  466. Use this if you want to hack on the server itself. There is no build step — the sources are plain
  467. ESM and run as they are.
  468. ### Node.js
  469. ```bash
  470. git clone https://github.com/marcomoauro/substack-mcp.git
  471. cd substack-mcp
  472. npm ci
  473. ```
  474. Then add to your MCP config:
  475. ```json
  476. {
  477. "mcpServers": {
  478. "substack-api": {
  479. "command": "node",
  480. "args": ["<FULL_PATH_TO_PROJECT>/src/index.js"],
  481. "env": {
  482. "SUBSTACK_PUBLICATION_URL": "<YOUR_PUBLICATION_URL>",
  483. "SUBSTACK_SESSION_TOKEN": "<YOUR_SESSION_TOKEN>",
  484. "SUBSTACK_USER_ID": "<YOUR_USER_ID>"
  485. }
  486. }
  487. }
  488. }
  489. ```
  490. ### Docker (build from source)
  491. ```bash
  492. git clone https://github.com/marcomoauro/substack-mcp.git
  493. cd substack-mcp
  494. docker build -t substack-mcp .
  495. ```
  496. Then add to your MCP config:
  497. ```json
  498. {
  499. "mcpServers": {
  500. "substack-api": {
  501. "command": "docker",
  502. "args": [
  503. "run", "-i", "--rm",
  504. "-e", "SUBSTACK_PUBLICATION_URL",
  505. "-e", "SUBSTACK_SESSION_TOKEN",
  506. "-e", "SUBSTACK_USER_ID",
  507. "substack-mcp"
  508. ],
  509. "env": {
  510. "SUBSTACK_PUBLICATION_URL": "<YOUR_PUBLICATION_URL>",
  511. "SUBSTACK_SESSION_TOKEN": "<YOUR_SESSION_TOKEN>",
  512. "SUBSTACK_USER_ID": "<YOUR_USER_ID>"
  513. }
  514. }
  515. }
  516. }
  517. ```
  518. ## 🪵 Logs
  519. The server logs what it does as one JSON object per line, on **stderr** — MCP clients collect it
  520. into their own log file (on macOS, Claude Desktop writes it to
  521. `~/Library/Logs/Claude/mcp-server-substack-api.log`). It is the fastest way to see what your LLM
  522. actually sent when a call does not do what you expected:
  523. ```json
  524. {"ts":"2026-08-07T10:12:03.114Z","level":"info","msg":"tool.call.start","tool":"create_draft_post","args":{"title":"My title","subtitle":"My subtitle","body":"…"}}
  525. {"ts":"2026-08-07T10:12:03.402Z","level":"info","msg":"substack.response","status":200,"duration_ms":287}
  526. {"ts":"2026-08-07T10:12:03.403Z","level":"info","msg":"create_draft_post.created","draft_id":167712345}
  527. ```
  528. Set the optional `SUBSTACK_MCP_LOG_LEVEL` env var alongside your credentials to change how much
  529. is written:
  530. | Value | What you get |
  531. |---|---|
  532. | `silent` | nothing |
  533. | `error` | failed calls only |
  534. | `warn` | the above, plus every answer the client received as an error — including calls rejected for bad arguments before they ran |
  535. | `info` *(default)* | the above, plus every tool call, request and response |
  536. | `debug` | the above, plus full payloads and every JSON-RPC message |
  537. Your session token is never written to the log, at any level.
  538. ## 💻 Popular MCP clients
  539. > For a complete list of MCP clients and their feature support, visit the [official MCP clients page](https://modelcontextprotocol.io/clients).
  540. | Client | Description |
  541. |----------------------------------------------------------------------------------------------------------------|-------------|
  542. | [Claude Desktop](https://claude.ai/download) | Desktop application for Claude AI |
  543. | [Cursor](https://www.cursor.com/) | AI-first code editor |
  544. | [Cline for VS Code](https://github.com/cline/cline) | VS Code extension for AI assistance |
  545. | [GitHub Copilot MCP](https://github.com/VikashLoomba/copilot-mcp) | VS Code extension for GitHub Copilot MCP integration |
  546. | [Windsurf](https://windsurf.com/editor) | AI-powered code editor and development environment |
  547. ## 🆘 Support
  548. - For issues with this MCP Server: Open an issue on [GitHub](https://github.com/marcomoauro/substack-mcp/issues)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.