# Reported issues for Substack MCP Server

Pod holds 7 of 7 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Substack MCP Server](/mcp/substack-mcp-server).

## Most discussed

### Question: should clients re-check trust if draft/publish boundaries change?

Hi Conor,

I’m Maaz, founder of Interlock, an open-source MCP runtime trust layer focused on post-approval MCP tool drift.

I was looking at substack-mcp and liked how explicit the safety boundary is: long-form posts stay draft-only, while Notes are clearly treated as public-publish actions.

The question I’m exploring is:

If a client approves this MCP server with that boundary, should the runtime notice if the approved surface changes later?

Examples:

- create_draft gains publish behavior
- 

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/9) · 2026-06-24 · closed · external user · 5 comments

### [Feature request] Upload image tool support local image path

First of all, thanks for building this MCP—it's been really helpful.

One improvement that would make it easier for AI agents to use is support for passing a local image file path instead of raw image bytes.

Currently, the agent has to read the image file, encode or load the bytes, and then pass the entire payload to the upload tool. This can be cumbersome, and some agents struggle with handling binary data reliably.

It would be great if the MCP could accept a local image path and read the fil

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/20) · 2026-07-10 · closed · outside contributor · 2 comments

### get_post_analytics: hardcoded pageSize=100 exceeds Substack API's accepted limit, causing 400

## Bug

`get_post_analytics` fails on every call with a 400 from Substack's API:

```
Substack API error (400) at https://<pub>.substack.com/api/v1/post_management/published?offset=0&limit=100&order_by=post_date&order_direction=desc: Validation error: {"location":"query","param":"limit","value":100,"msg":"Invalid value"}
```

## Root cause

`ApiClient.getPostAnalytics` (`src/api/client.ts`) pages through the published-posts feed looking for the requested post ID, using a hardcoded `pageSize = 10

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/28) · 2026-08-02 · closed · external user · 1 comment

### Block non-monotonic versions in automated publishing

The automated publish workflow treats any local version unequal to the published version as publishable. A self-consistent but lower, previously unpublished version can therefore pass the metadata gate and run `npm publish`, which can move npm's `latest` dist-tag backward.

Found during exact-SHA review of #37; pre-existing and intentionally kept outside that drift-repair PR.

## Completion criteria
- compare the local and published versions with a semver-aware implementation
- first publication

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/38) · 2026-08-29 · closed · 0 comments

### Two 11-second delays: blocking auth check before connect, and SIGTERM ignored at PID 1

Two independent 11-second delays, both found while adversarially reviewing the Dockerfile in #29. Neither was introduced by that PR; both are pre-existing and both are reproducible in a container.

## 1. `validateAuth()` blocks the MCP handshake, with no fetch timeout

`src/index.ts:31` awaits `client.validateAuth()` **before** `server.connect(transport)`, and nothing in `src/api/client.ts` sets an `AbortSignal` or timeout on any `fetch`. So a network that hangs rather than refuses stalls `initi

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/31) · 2026-08-03 · closed · 0 comments

### Add readOnlyHint/destructiveHint annotations to tools

Tools register without MCP [tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations). Adding them helps clients render accurate consent UI:

- **`readOnlyHint: true`**: `get_subscriber_count`, `list_published_posts`, `list_drafts`, `get_post`, `get_draft`, `get_post_comments`.
- **Write, additive** (`readOnlyHint: false`): `create_draft`, `update_draft`, `upload_image`.
- **`create_note` / `create_note_with_link`**: these publish public content immediately — worth 

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/4) · 2026-06-10 · closed · 0 comments

### README 'cannot publish' banner conflicts with create_note (which publishes immediately)

The top-of-README banner states:

> **Safe by design:** This server can create and edit drafts but cannot publish or delete posts.

But `create_note` and `create_note_with_link` publish Substack Notes immediately — the tool descriptions correctly say "publishes immediately," and the Write table lists them. So the banner's blanket "cannot publish" claim is accurate only for long-form *posts*, not Notes.

Suggestion: tighten the banner to scope the guarantee, e.g.:

> **Safe by design:** This serv

[Read the thread](https://github.com/conorbronsdon/substack-mcp/issues/3) · 2026-06-10 · closed · 0 comments

## Most recent

The remaining reports are on [the project's issue tracker](https://github.com/conorbronsdon/substack-mcp/issues).