home / mcp / substack mcp server

Substack MCP Server

Provides programmatic access to Substack actions via MCP, enabling drafts, image uploads, live updates, and notes.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "arthurcolle-substack-mcp": {
      "command": "bash",
      "args": [
        "-c",
        "source ~/.substackrc && python3 $(pwd)/substack_mcp/server.py"
      ],
      "env": {
        "SUBSTACK_SID": "your-cookie-value-here",
        "SUBSTACK_PUBLICATION": "your-publication.substack.com"
      }
    }
  }
}

You can control Substack posts programmatically using this MCP server. It lets you create, update, and publish drafts, upload images, run live blogs with real-time updates, post notes, and work with Substack’s editor structure through a robust MCP interface.

How to use

You interact with the Substack MCP server through an MCP client to manage drafts, publish posts, upload media, and run live blogging sessions. Start by configuring the MCP client to point at this server, then use the available tools to perform common tasks such as creating a draft, adding content, uploading images, starting a live blog, and publishing when you’re ready.

How to install

Prerequisites: you need Python and Git installed on your system. Ensure you have network access to install dependencies.

# Clone the repo
git clone https://github.com/acolle/substack-mcp.git
cd substack-mcp

# Install dependencies
pip install -r requirements.txt

Configuration and setup

You must provide your Substack publication identifier and session cookie value. Create a credentials file that your MCP server will source when starting.

# Create ~/.substackrc
cat > ~/.substackrc << 'EOF'
export SUBSTACK_PUBLICATION="your-publication.substack.com"
export SUBSTACK_SID="your-cookie-value-here"
EOF

Run the MCP server with Claude Code or your MCP client

Add the MCP server to your client configuration to run the server locally. The following command shows how to start the server within a shell process that your client can spawn.

# Add the MCP server to Claude Code
claude mcp add substack \
  --command "bash" \
  --args "-c" "source ~/.substackrc && python3 $(pwd)/substack_mcp/server.py"

Inline alternative configuration

If you prefer a local JSON configuration, you can place the following in your Claude JSON configuration.

{
  "mcpServers": {
    "substack": {
      "command": "bash",
      "args": ["-c", "source ~/.substackrc && python3 /path/to/substack-mcp/substack_mcp/server.py"]
    }
  }
}

Notes on credentials and security

Keep your Substack session cookie secure. Do not share your ~/.substackrc file or the session value in SUBSTACK_SID. Rotate credentials if you suspect any compromise.

Available tools

substack_create_draft

Create a new draft post for a Substack publication.

substack_update_draft

Update the content of an existing draft.

substack_append_to_draft

Append content to a draft, useful for live blogging.

substack_add_code_block

Insert a code block into a Substack draft.

substack_add_image

Upload and attach an image to a draft post.

substack_publish

Publish a draft post to Substack.

substack_post_note

Post a short Note to Substack Notes.

substack_get_drafts

Retrieve a list of current drafts.

substack_get_posts

Retrieve a list of published posts.

substack_live_blog_start

Initiate a live blogging session for real-time updates.

substack_live_blog_end

End the active live blogging session.