Skip to main content

​
Use Cases and Benefits

You can use the Heroku MCP Server to improve various core developer workflows:
  • App lifecycle management: Empower agents to handle deploying, scaling, restarting, viewing logs, and monitoring your applications.
  • Database operations: Enable actions on your Heroku Postgres databases.
  • Add-on management: Enable agents to discover available add-ons and attach or detach resources to your apps.
  • Scaling and performance: Facilitate intelligent scaling of your application resources.
The Heroku MCP Server is open-source and available on GitHub. The Heroku MCP Server works on Common Runtime, Cedar Private and Shield Spaces, and Fir Private Spaces.

​
How It Works

The Heroku MCP Server uses the Heroku CLI to execute actions. To maximize performance and responsiveness, the server runs the Heroku CLI in Read-Eval-Print Loop (REPL) mode. This enables faster command execution and more efficient multitool operations as it doesn’t require launching a new CLI process for each action. The Heroku MCP Server requires the Heroku CLI to be installed globally (v10.8.1+). To confirm you have the correct version, run heroku --version.

​
Configure the Heroku Platform MCP Server

You can configure Claude Desktop, Zed, Cursor, Windsurf, and other clients to work with the Heroku Platform MCP Server.

​
Configure the Heroku Platform MCP Server with heroku mcp:start

Use heroku mcp:start to launch the Heroku Platform MCP Server. We recommend this method as it leverages your existing Heroku CLI authentication, so you don’t need to set the HEROKU_API_KEY environment variable. The heroku mcp:start command is available in Heroku CLI version 10.8.1 and later. There are several benefits to configuring with heroku mcp:start:
  • No need to manage or expose your Heroku API key
  • Uses your current Heroku CLI authentication context
  • Works seamlessly with supported clients

​
Example Configuration for Claude Desktop

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

​
Example Configuration for Zed

{
  "context_servers": {
    "heroku": {
      "command": {
        "path": "heroku",
        "args": ["mcp:start"]
      }
    }
  }
}

​
Example Configuration for Cursor

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

​
Example Configuration for Windsurf

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

​
Example Configuration for Cline

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

​
Example Configuration for VSCode

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

​
Example Configuration for Trae

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}
When you use heroku mcp:start, the server authenticates using your current Heroku CLI session so you don’t need to set the HEROKU_API_KEY environment variable. We recommend you use heroku mcp:start, but if you prefer to use an API key, you can use the alternate configuration below.

​
Configure the Heroku Platform MCP Server with npx

You can also launch the Heroku Platform MCP Server using the npx -y @heroku/mcp-server command. This method requires you to set the HEROKU_API_KEY environment variable with your Heroku authorization token.

​
Authentication

Generate a Heroku authorization token with one of these methods:
  • Use the Heroku CLI command:
heroku authorizations:create
  • Use an existing token in the CLI
heroku auth:token
Click your avatar, then select Account Settings.
  • Open the Applications tab.
  • Next to Authorizations, click Create authorization.
Copy the token and use it as your HEROKU_API_KEY to configure the Heroku MCP Server.

​
Example Configuration for Claude Desktop

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

​
Example Configuration for Zed

{
  "context_servers": {
    "heroku": {
      "command": {
        "path": "npx",
        "args": ["-y", "@heroku/mcp-server"],
        "env": {
          "HEROKU_API_KEY": ""
        }
      }
    }
  }
}

​
Example Configuration for Cursor

{
  "mcpServers": {
    "heroku": {
      "command": "npx -y @heroku/mcp-server",
      "env": {
        "HEROKU_API_KEY": ""
      }
    }
  }
}

​
Example Configuration for Windsurf

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

​
Example Configuration for Cline

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

​
Example Configuration for VSCode

{
  "mcp": {
    "servers": {
      "heroku": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@heroku/mcp-server"],
        "env": {
          "HEROKU_API_KEY": ""
        }
      }
    }
  }
}

​
Example Configuration for Trae

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": ""
      }
    }
  }
}
When you use npx -y @heroku/mcp-server, you must set the HEROKU_API_KEY environment variable with your Heroku authorization token.

​
Available Tools

​
Application Management

  • list_apps - List all Heroku apps. You can filter apps by personal, collaborator, team, or space.
  • get_app_info - Get detailed information about an app, including its configuration, dynos, and add-ons.
  • create_app - Create a new app with customizable settings for region, team, and space.
  • rename_app - Rename an existing app.
  • transfer_app - Transfer ownership of an app to another user or team.
  • deploy_to_heroku - Deploy projects to Heroku with an app.json configuration, supporting team deployments, spaces, and environment setups.
  • deploy_one_off_dyno - Execute code or commands in a sandboxed environment on a Heroku one-off dyno. Supports file creation, network access, environment variables, and automatic cleanup. Ideal for running scripts, tests, or temporary workloads.

​
Process & Dyno Management

  • ps_list - List all dynos for an app.
  • ps_scale - Scale the number of dynos up or down, or resize dynos.
  • ps_restart - Restart specific dynos, process types, or all dynos.

​
Add-ons

  • list_addons - List all add-ons for all apps or for a specific app.
  • get_addon_info - Get detailed information about a specific add-on.
  • create_addon - Provision a new add-on for an app.

​
Maintenance & Logs

  • maintenance_on - Enable maintenance mode for an app.
  • maintenance_off - Disable maintenance mode for an app.
  • get_app_logs - View application logs.

​
Pipeline Management

  • pipelines_create - Create a new pipeline.
  • pipelines_promote - Promote apps to the next stage in a pipeline.
  • pipelines_list - List available pipelines.
  • pipelines_info - Get detailed pipeline information.

​
Team & Space Management

  • list_teams - List teams you belong to.
  • list_private_spaces - List available spaces.

​
PostgreSQL Database Management

  • pg_psql - Execute SQL queries against the Heroku PostgreSQL database.
  • pg_info - Display detailed database information.
  • pg_ps - View active queries and execution details.
  • pg_locks - View database locks and identify blocking transactions.
  • pg_outliers - Identify resource-intensive queries.
  • pg_credentials - Manage database credentials and access.
  • pg_kill - Terminate specific database processes.
  • pg_maintenance - Show database maintenance information.
  • pg_backups - Manage database backups and schedules.
  • pg_upgrade - Upgrade PostgreSQL to a newer version.

​
Debugging

You can use the MCP inspector or the VS Code Run and Debug function to run and debug the server.
  • Link the project as a global CLI using npm link from the project root.
  • Build with npm run build:dev or watch for file changes and build automatically with npm run build:watch.

​
Use the MCP Inspector

Use the MCP inspector with no breakpoints in the code: 
# Breakpoints are not available
npx @modelcontextprotocol/inspector heroku-mcp-server
Alternatively, if you installed the package in a specific directory or are actively developing on the Heroku MCP server: 
cd /path/to/servers
npx @modelcontextprotocol/inspector dist/index.js

​
Use the VS Code Run and Debug Function

Use the VS Code Run and Debug launcher with fully functional breakpoints in the code:
  • Locate and select the run debug.
  • Select the configuration labeled MCP Server Launcher in the dropdown.
  • Select the Run/Debug button.

​
VS Code / Cursor Debugging Setup

To set up local debugging with breakpoints:
  • Store your Heroku auth token in the VS Code user settings:
Open the Command Palette with Cmd/Ctrl + Shift + P.
  • Type Preferences: Open User Settings (JSON).
  • Add this snippet: 
{
  "heroku.mcp.authToken": "your-token-here"
}
  • Create or update .vscode/launch.json:
{
     "version": "0.2.0",
     "configurations": [
       {
         "type": "node",
         "request": "launch",
         "name": "MCP Server Launcher",
         "skipFiles": ["/**"],
         "program": "${workspaceFolder}/node_modules/@modelcontextprotocol/inspector/bin/cli.js",
         "outFiles": ["${workspaceFolder}/**/dist/**/*.js"],
         "env": {
           "HEROKU_API_KEY": "${config:heroku.mcp.authToken}",
           "DEBUG": "true"
         },
         "args": ["heroku-mcp-server"],
         "sourceMaps": true,
         "console": "integratedTerminal",
         "internalConsoleOptions": "neverOpen",
         "preLaunchTask": "npm: build:watch"
       },
       {
         "type": "node",
         "request": "attach",
         "name": "Attach to Debug Hook Process",
         "port": 9332,
         "skipFiles": ["/**"],
         "sourceMaps": true,
         "outFiles": ["${workspaceFolder}/dist/**/*.js"]
       },
       {
         "type": "node",
         "request": "attach",
         "name": "Attach to REPL Process",
         "port": 9333,
         "skipFiles": ["/**"],
         "sourceMaps": true,
         "outFiles": ["${workspaceFolder}/dist/**/*.js"]
       }
     ],
     "compounds": [
       {
         "name": "Attach to MCP Server",
         "configurations": ["Attach to Debug Hook Process", "Attach to REPL Process"]
       }
     ]
   }
  • Create .vscode/tasks.json:
{
     "version": "2.0.0",
     "tasks": [
       {
         "type": "npm",
         "script": "build:watch",
         "group": {
            "kind": "build",
            "isDefault": true
         },
         "problemMatcher": ["$tsc"]
       }
     ]
   }
  • (Optional) Set breakpoints in your TypeScript files.
  • Press F5 or use the Run and Debug sidebar.
The debugger automatically builds your TypeScript files before launching.

​
Additional Reading