Overview

The Heroku MCP Server is a Model Context Protocol (MCP) implementation that exposes Heroku Platform operations as context tools for large language models and other MCP-capable clients. It enables LLM-driven workflows to inspect and manage Heroku resources—apps, dynos, add-ons, and databases—so you can automate deployment, scaling, maintenance, and diagnostics from natural-language interfaces or developer tools that support MCP.

Two ways to run the server are supported: using your local Heroku CLI session (recommended) or running the packaged Node module and supplying a Heroku API token. The CLI-based approach reuses your existing authentication, reducing secret management. The MCP server is designed to be used with desktop LLM clients, IDE integrations, and other tools that connect to an MCP server over stdio or a socket.

Features

Exposes Heroku platform capabilities as LLM-friendly tools (apps, dynos, add-ons, databases)
Supports Common Runtime, Cedar Private, Shield Spaces, and Fir Private Spaces
CLI-based launch uses your current Heroku CLI session (no HEROKU_API_KEY required)
Alternate launch via npx with HEROKU_API_KEY for environments without a CLI session
Read and write operations: list/create/update/delete apps, scale dynos, manage add-ons, inspect and connect to Postgres
Secure authenticated access to Heroku Platform APIs
Configurable for MCP clients like Claude Desktop, Cursor, Zed, and VS Code

Installation / Configuration

Prerequisites:

Heroku CLI v10.8.1 or newer (required if using the CLI-based start)
Node.js / npx if you prefer the packaged server route
A Heroku account and appropriate permissions for the resources you intend to manage

Recommended: start using your existing Heroku CLI session

This method leverages the Heroku CLI authentication context. No HEROKU_API_KEY environment variable is needed.

Start from a shell:

# start the MCP server using your Heroku CLI context
heroku mcp:start

Example MCP client config (stdio command pattern):

{
  "mcp": {
    "servers": {
      "heroku": {
        "type": "stdio",
        "command": "heroku",
        "args": ["mcp:start"]
      }
    }
  }
}

Alternate: run the published package with an API token

If you cannot run the Heroku CLI where the MCP server runs, use npx and set HEROKU_API_KEY.

Generate a token:

# create a token via the Heroku CLI
heroku authorizations:create

# or get the existing CLI token
heroku auth:token

Start the server with npx:

HEROKU_API_KEY=your_token_here npx -y @heroku/mcp-server

Client configuration example (npx approach):

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Available Tools

The MCP server exposes a set of tools corresponding to common Heroku actions. Typical tools include:

Tool name	Action	Scope
apps:list	List apps accessible to the token/CLI user	account/organization
apps:create	Create a new Heroku app	account/org
apps:info	Fetch app metadata and config vars	single app
dynos:list	List dynos for an app	app
dynos:scale	Scale dyno types (web, worker)	app
dynos:run	Run one-off dynos / run commands	app
addons:list	List add-ons attached to an app	app
addons:create	Provision an add-on (e.g., Postgres)	app
db:credentials	Retrieve database credentials / connection info	addon
db:backups	Trigger or inspect Postgres backups	addon
logs:tail	Stream application logs	app

Tools are modeled to return structured data so LLMs and clients can reason about, show, or act on the results. The exact tool names and parameters are available by querying the MCP server’s tool registry after startup.

Use Cases

Dev productivity: Ask your LLM assistant to “list my staging apps and show which ones have >1 web dyno,” then use the assistant to scale down or spin up dynos with a follow-up command.
Troubleshooting: Have a model check recent logs and identify errors, then create a one-off dyno to run a diagnostic script or apply a temporary configuration change.
Database tasks: Request the assistant to create a Heroku Postgres add-on for an app, retrieve connection credentials, or initiate a backup and report status.
CI / deployment workflows: Use an MCP-enabled CI helper to create an app, provision add-ons, deploy a release, and scale dynos automatically from a higher-level instruction like “deploy the feature branch to a review app.”
Onboarding automation: New team members can ask the assistant to “show all apps I have access to and list the ones that use Postgres,” easing permission checks and environment discovery.

Security and Best Practices

Prefer launching with heroku mcp:start so the server reuses your local CLI authentication; this avoids storing long-lived tokens in environment variables.
If you must use HEROKU_API_KEY, scope tokens and rotate them regularly. Treat tokens as secrets.
Ensure the MCP client and the machine running the server are trusted; the server grants programmatic access to platform operations.

Resources

Repository: https://github.com/heroku/heroku-mcp-server
Heroku CLI: https://devcenter.heroku.com/articles/heroku-cli
Heroku API docs: https://devcenter.heroku.com/articles/platform-api

If you plan to integrate this server into an LLM-enabled workflow or an IDE, start by launching the server with your preferred authentication method and then query the MCP tool registry to discover supported operations.

Heroku MCP Server: Manage Apps, Dynos, Databases