WriteStack MCP server

A connected client can draft and update Substack Notes, place them on the writer’s queue, work with articles, read statistics and activity, and set Buffer cross-posts. Every call runs as the authenticated WriteStack user and never touches another account.

Endpoint

https://www.writestack.io/api/mcp/mcp

Transport

Streamable HTTP

Legacy SSE probe

https://www.writestack.io/api/mcp/mcp/sse returns HTTP 405. Use the endpoint above.

Acts as

The signed-in WriteStack user

Flow

OAuth 2.1, authorization code with PKCE (S256)

Authorize

https://www.writestack.io/oauth/authorize

Token

https://www.writestack.io/api/oauth/token

Client registration

https://www.writestack.io/api/oauth/register

Server metadata

https://www.writestack.io/.well-known/oauth-authorization-server

Resource metadata

https://www.writestack.io/.well-known/oauth-protected-resource

Scopes

mcp, offline_access

Grant types

authorization_code, refresh_token

Client auth

Public clients, no secret (token_endpoint_auth_method: none)

For clients without OAuth, create an API key in WriteStack under Settings → MCP (www.writestack.io/settings) and send it as Authorization: Bearer <key>. Treat the key like a password. Revoke it in Settings if it leaks.

ClaudeClaude Desktop and Claude on the webSetup guideChatGPTChatGPT Desktop and the web appSetup guideNotionNotion AI custom connectorsSetup guide

A client that reads a local config file and has no OAuth support can reach the server through mcp-remote with an API key header:

{
  "mcpServers": {
    "writestack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.writestack.io/api/mcp/mcp",
        "--header",
        "Authorization: Bearer ws_your_api_key"
      ]
    }
  }
}

Note bodies are Markdown, and a line break is a blank line (two newlines). Before drafting new text, call get_writing_style unless the writer already pasted full style instructions. Call list_tags before assigning tag names.

Remote images go in imageUrl, up to five https URLs per note. WriteStack fetches and stores them.

• list_notesRead

  List notes, optionally by status or tag. Status evergreen means notes set to repeat. Paginate with skip and read hasMore.

• get_noteRead

  Read one note, including auto-restack, Buffer channels, and any per-channel Buffer text or images.

• get_writing_styleRead

  Read the saved note style, topics, and onboarding context.

• list_tagsRead

  List category names. Tags also decide which reserved queue times a note can take.

• create_noteWrite

  Create a draft or ready note. Optional auto-restack 1–168 hours after it publishes, plus optional Buffer channels and per-channel posts.

• create_many_notesWrite

  Create several notes in one call. Each note has its own status, tags, images, previews, auto-restack, and Buffer settings.

• update_noteIrreversible

  Replace the fields you pass: content, status, tags, auto-restack, Buffer channels, per-channel posts, or link preview. No undo, so read the note and confirm first. autoRestackAfterHours: null turns auto-restack off, and an empty bufferChannelIds clears channels.

The template is a set of weekly times. Each time stays open, reserves tags, or accepts only untagged notes. A note takes a reserved time when it shares any of that time’s tags. Untagged notes use open and untagged-only times. A time can also carry default Buffer channels, which replace the note’s channels when it lands there.

• get_scheduleRead

  Read the weekly template, including reserved tags, untagged-only times, and default Buffer channels.

• get_queueRead

  List notes that already have a posting time. Paginate with skip.

• get_next_available_slotsRead

  Preview the next free times. Pass tagNames to preview one note’s lane, or omit them to list every free time in order.

• get_schedule_capacityRead

  Read the plan limit, the current scheduled count, how many remain, and whether the account is unlimited.

• schedule_notesIrreversible

  Place notes on the next template times, routed by each note’s tags. Use this unless the writer asks for exact times.

• schedule_notes_with_custom_datesIrreversible

  Place each note at an explicit future ISO 8601 time. Use this when the writer names times or has no template.

Article tools only see newsletters the writer enabled in WriteStack Articles. Call list_article_newsletters and ask which one to use before creating, pushing, or scheduling. Never guess a publicationId.

Bodies are GitHub-flavored Markdown that Substack accepts: headings, bold, italic, strikethrough, inline code, links, images, lists, blockquotes, :::pullquote, :::callout, and a :::paywall::: line. Voice and video embeds are not supported.

create_article and update_article save in WriteStack only. Pushing and scheduling go through the writer’s Chrome extension. With WriteStack open, a push usually finishes in seconds. Otherwise it waits until WriteStack is next open.

• list_article_newslettersRead

  List enabled newsletters with publicationId, title, URL, and which one is primary.

• list_articlesRead

  List articles from enabled newsletters, optionally by status or publicationId.

• get_articleRead

  Read one article: Markdown body, newsletter, content version, and Substack draft or schedule status.

• create_articleWrite

  Create a planned article on the newsletter the writer chose.

• update_articleIrreversible

  Replace title, subtitle, body, images, or Substack settings (audience, comments, SEO, slug, social title, publishAt) in WriteStack. No undo.

• generate_articleWrite

  Start AI generation for a planned article. Returns right away while the draft is written in the background.

• push_article_to_substackIrreversible

  Send or update the article as a Substack draft through the Chrome extension.

• schedule_article_on_substackWrite

  Schedule the article on Substack at publishAt. Pushes the draft first if it is not synced.

• unschedule_article_on_substackIrreversible

  Remove the article from the Substack schedule. The draft stays on Substack.

• get_article_substack_statusRead

  Read the draft URL, scheduled time, and last sync error.

Statistics tools need the matching WriteStack feature and a current extension. If a call fails, the error text says what to do next.

• get_notes_statisticsRead

  Published Note analytics: impressions, clicks, reactions, comments, restacks, profile visits, shares, subscribers, and an audience split when Substack stored one. Filter by date, sort, search, and paginate.

• get_posts_statisticsRead

  Post statistics for every newsletter on Posts Statistics: views, opens, open rate, delivery, likes, comments, restacks, shares, clicks, signups, subscriber split, and ARR. Use the returned openRate; email traffic share is a different number. Needs extension 1.5.25 or newer.

• list_activitiesRead

  Substack comments and mentions, the same as the WriteStack activity feed, without the writer’s own posts. Paginate with skip and limit (at most 50).

Call list_buffer_channels before passing channel ids. Only returned ids are accepted, up to 20 per note. An empty list means the writer has not connected Buffer.

• list_buffer_channelsRead

  List connected Buffer channels with id, name, and service.

• get_feature_suggestion_linkRead

  Return writestack.io/features, where the writer can post the idea for votes. It does not submit anything.

• The server cannot publish Notes to Substack. The writer syncs with the yellow Sync button in WriteStack.
• The server cannot unschedule Notes. The writer does that in WriteStack.
• update_note and update_article overwrite the fields you send. Read first, confirm, then write.
• Never schedule more Notes than get_schedule_capacity reports, unless unlimited is true.
• Never invent publication ids, tag names, or Buffer channel ids. Read them from the matching list tool.
• Auto-restack runs 1–168 hours after a Note publishes and needs WriteStack extension 1.4.78 or newer.
• Personal data practices are in the privacy policy at www.writestack.io/privacy. Questions go to orel@writestack.io.