Substack MCP Server

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.

🛠 Available Tools

The seven tools below read substack.com, not your publication. They are about the account as a reader — what it subscribes to, what is in its inbox and feed — which is a different host and a different id space from the publisher surface above.

📋 Requirements

• Substack tokens, follow my guide to obtain them:
  • Session token
  • Publication URL
  • User ID
• An LLM client that supports Model Context Protocol (MCP), such as Claude Desktop, Cursors, or GitHub Copilot
• Docker

🔌 Installation

Introduction

The installation process is standardized across all MCP clients. It involves manually adding a configuration object to your client’s MCP configuration JSON file.

If you’re unsure how to configure an MCP with your client, please refer to your MCP client’s official documentation.

🧩 Engines

This option requires Node.js 22 or newer to be installed on your system.

1. Add the following to your MCP configuration file:

{
  "mcpServers": {
    "substack-api": {
      "command": "npx",
      "args": ["-y", "substack-mcp@latest"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "",
        "SUBSTACK_SESSION_TOKEN": "",
        "SUBSTACK_USER_ID": ""
      }
    }
  }
}

2. Replace , and `` with your credentials.

This option requires Docker to be installed on your system.

1. Add the following to your MCP configuration file:

{
  "mcpServers": {
    "substack-api": {
      "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": "",
        "SUBSTACK_SESSION_TOKEN": "",
        "SUBSTACK_USER_ID": ""
      }
    }
  }
}

2. Replace , and `` with your credentials.

🏗 Running from Source

Use this if you want to hack on the server itself. There is no build step — the sources are plain ESM and run as they are.

Node.js

git clone https://github.com/marcomoauro/substack-mcp.git
cd substack-mcp
npm install

Then add to your MCP config:

{
  "mcpServers": {
    "substack-api": {
      "command": "node",
      "args": ["/src/index.js"],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "",
        "SUBSTACK_SESSION_TOKEN": "",
        "SUBSTACK_USER_ID": ""
      }
    }
  }
}

Docker

git clone https://github.com/marcomoauro/substack-mcp.git
cd substack-mcp
docker build -t substack-mcp .

Then add to your MCP config:

{
  "mcpServers": {
    "substack-api": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SUBSTACK_PUBLICATION_URL",
        "-e", "SUBSTACK_SESSION_TOKEN",
        "-e", "SUBSTACK_USER_ID",
        "substack-mcp"
      ],
      "env": {
        "SUBSTACK_PUBLICATION_URL": "",
        "SUBSTACK_SESSION_TOKEN": "",
        "SUBSTACK_USER_ID": ""
      }
    }
  }
}

🪵 Logs

The server logs what it does as one JSON object per line, on stderr — MCP clients collect it into their own log file (on macOS, Claude Desktop writes it to ~/Library/Logs/Claude/mcp-server-substack-api.log). It is the fastest way to see what your LLM actually sent when a call does not do what you expected:

{"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":"…"}}
{"ts":"2026-08-07T10:12:03.402Z","level":"info","msg":"substack.response","status":200,"duration_ms":287}
{"ts":"2026-08-07T10:12:03.403Z","level":"info","msg":"create_draft_post.created","draft_id":167712345}

Set the optional SUBSTACK_MCP_LOG_LEVEL env var alongside your credentials to change how much is written:

Your session token is never written to the log, at any level.

💻 Popular Clients that supports MCPs

For a complete list of MCP clients and their feature support, visit the official MCP clients page.

🆘 Support

• For issues with this MCP Server: Open an issue on GitHub