Heroku Code MCP server

Heroku Code MCP

A compact MCP server for the Heroku Platform API using a Code Mode pattern: search + execute + auth_status.

<!-- mcp-name: io.github.dsouzaAnush/heroku-code-mcp -->

Heroku Code MCP gives agent clients a small, token-efficient control surface for Heroku operations. Pair it with Heroku Skills when you want workflow guidance, safety checks, and Heroku product context alongside live API tools.

Design references:

• Cloudflare Code Mode MCP
• Anthropic: Building Effective Agents

Quick Start

Default MCP URL: http://127.0.0.1:3000/mcp

git clone https://github.com/dsouzaAnush/heroku-code-mcp.git
cd heroku-code-mcp
npm install
npm run build
npm test

Seed auth from the Heroku CLI:

heroku auth:whoami
npm run seed:token

Start the server:

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64="<seed-output-key>" \
PORT=3000 HOST=127.0.0.1 npm run dev

Smoke test:

curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

Before npm publication, the package can also run from GitHub:

HOST=127.0.0.1 PORT=3333 \
TOKEN_STORE_PATH="$HOME/.heroku-code-mcp/tokens.json" \
TOKEN_ENCRYPTION_KEY_BASE64="<base64-32-byte-key>" \
WRITE_CONFIRMATION_SECRET="<random-secret>" \
npx -y github:dsouzaAnush/heroku-code-mcp

Install in Agent Clients

Claude Code

Install the companion plugin for skills plus MCP wiring:

claude plugin marketplace add dsouzaAnush/heroku-plugin
claude plugin install heroku@heroku-plugin
claude plugin enable heroku@heroku-plugin

Or add the running MCP server directly:

claude mcp add \
  --transport http \
  --scope local \
  heroku-code-mcp \
  http://127.0.0.1:3000/mcp \
  --header "x-user-id: default"

Claude Desktop

Use the HTTP endpoint directly when supported:

{
  "mcpServers": {
    "heroku-code-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

For Desktop builds that expect stdio servers, bridge through mcp-remote:

{
  "mcpServers": {
    "heroku-code-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--allow-http", "--header", "x-user-id:default"]
    }
  }
}

Build a .mcpb bundle with:

npm run build:mcpb

Codex

Codex uses Heroku Plugin for skills and optional MCP wiring:

codex plugin marketplace add dsouzaAnush/heroku-plugin --ref main

Enable heroku-plugin@heroku-plugin in the Codex Plugins tab, or add:

[plugins."heroku-plugin@heroku-plugin"]
enabled = true

Run this MCP server on http://127.0.0.1:3333/mcp when you want live Heroku API tools through the plugin.

Cursor

git clone https://github.com/dsouzaAnush/heroku-plugin.git
cursor agent --plugin-dir heroku-plugin

Add the MCP server to ~/.cursor/mcp.json or project-local .cursor/mcp.json:

{
  "mcpServers": {
    "heroku-code-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

Other MCP Clients

Use streamable HTTP:

Shortened. The full README is on GitHub.