Skip to main content
Glama
Heroku MCP server

Heroku MCP server

Official
by heroku

heroku-mcp-server

Install MCP Server

The Heroku Platform MCP Server works on Common Runtime, Cedar Private and Shield Spaces, and Fir Private Spaces.

Prerequisites

Related MCP server: ChatGPT Gateway MCP Nyan

Deploy on Heroku

Deploy

Overview

The Heroku Platform MCP Server is a specialized Model Context Protocol (MCP) implementation designed to facilitate seamless interaction between large language models (LLMs) and the Heroku Platform. This server provides a robust set of tools and capabilities that enable LLMs to read, manage, and operate Heroku Platform resources.

Key Features:

  • Direct interaction with Heroku Platform resources through LLM-driven tools

  • Secure and authenticated access to Heroku Platform APIs, leveraging the Heroku CLI

  • Natural language interface for Heroku Platform interactions

Note: The Heroku Platform MCP Server is currently in early development. As we continue to enhance and refine the implementation, the available functionality and tools may evolve. We welcome feedback and contributions to help shape the future of this project.

Note: The Heroku Platform MCP Server requires the Heroku CLI to be installed globally (v10.8.1+). Ensure you have the correct version by running 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"
    }
  }
}

Note: 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 -y @heroku/mcp-server

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.

Generating the HEROKU_API_KEY

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

    Copy the token and use it as your HEROKU_API_KEY in the following steps.

  • In your Heroku Dashboard:

    1. Select your avatar, then select Account Settings.

    2. Open the Applications tab.

    3. Next to Authorizations, click Create authorization.

Example configuration for Claude Desktop:

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

Example configuration for Zed:

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

Example configuration for Cursor:

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

Example configuration for Windsurf:

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

Example configuration for Cline:

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

Example configuration for VSCode:

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

Example configuration for Trae:

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

Note: 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, private 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.

  1. Link the project as a global CLI using npm link from the project root.

  2. 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:

  1. Locate and select the run debug.

  2. Select the configuration labeled "MCP Server Launcher" in the dropdown.

  3. Select the run/debug button.

VS Code / Cursor Debugging Setup

To set up local debugging with breakpoints:

  1. Store your Heroku auth token in the VS Code user settings:

    • Open the Command Palette (Cmd/Ctrl + Shift + P).

    • Type Preferences: Open User Settings (JSON).

    • Add the following snippet:

    {
      "heroku.mcp.authToken": "your-token-here"
    }
  2. Create or update .vscode/launch.json:

    {
      "version": "0.2.0",
      "configurations": [
        {
          "type": "node",
          "request": "launch",
          "name": "MCP Server Launcher",
          "skipFiles": ["<node_internals>/**"],
          "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": ["<node_internals>/**"],
          "sourceMaps": true,
          "outFiles": ["${workspaceFolder}/dist/**/*.js"]
        },
        {
          "type": "node",
          "request": "attach",
          "name": "Attach to REPL Process",
          "port": 9333,
          "skipFiles": ["<node_internals>/**"],
          "sourceMaps": true,
          "outFiles": ["${workspaceFolder}/dist/**/*.js"]
        }
      ],
      "compounds": [
        {
          "name": "Attach to MCP Server",
          "configurations": ["Attach to Debug Hook Process", "Attach to REPL Process"]
        }
      ]
    }
  3. Create .vscode/tasks.json:

    {
      "version": "2.0.0",
      "tasks": [
        {
          "type": "npm",
          "script": "build:watch",
          "group": {
            "kind": "build",
            "isDefault": true
          },
          "problemMatcher": ["$tsc"]
        }
      ]
    }
  4. (Optional) Set breakpoints in your TypeScript files.

  5. Press F5 or use the Run and Debug sidebar.

Note: the debugger automatically builds your TypeScript files before launching.

Environment Variables

The Heroku Platform MCP Server supports the following environment variables:

HEROKU_API_KEY

Your Heroku authorization token. Required for authentication with the Heroku Platform.

MCP_SERVER_REQUEST_TIMEOUT

Timeout in milliseconds for command execution. Defaults to 15000 (15 seconds) if not set.

Example configuration with custom timeout:

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

MCP_SERVER_IDLE_TIMEOUT

Timeout in milliseconds of inactivity after which the underlying Heroku CLI process is shut down so an idle server does not keep a CLI process running. The process is started on the first tool call and transparently restarted on the next call after a teardown. Defaults to 300000 (5 minutes) if not set; set to 0 to disable idle teardown and keep the process running for the lifetime of the server.

Available Tools

33 tools
create_addonA

Create a new Heroku add-on for an application. Use this tool when you need to: 1) Provision a new add-on for your app, 2) Specify a particular service and plan, 3) Set a custom name for the add-on or attachment. The tool handles the provisioning process and returns the new add-on's details.

Inputs: app (required), serviceAndPlan (required), as, name.

create_appA

Create a new Heroku application with customizable settings. Use this tool when a user wants to: 1) Create a new app with a specific name, 2) Create an app in a particular region (US/EU), 3) Create an app within a team, or 4) Create an app in a private space. The tool handles name generation if not specified and returns the new app's details.

Inputs: app, region, space, team.

deploy_to_herokuA

Deploy projects to Heroku, replaces manual git push workflows. Use this tool when you need to: 1) Deploy a new application with specific app.json configuration, 2) Update an existing application with new code, 3) Configure team or private space deployments, or 4) Set up environment-specific configurations. The tool handles app creation, source code deployment, and environment setup. Requires valid app.json in workspace or provided via configuration. Supports team deployments, private spaces, and custom environment variables.Use apps_list tool with the "all" param to get a list of apps for the user to choose from when deploying to an existing app and the app name was not provided.

Inputs: name (required), rootUri (required), appJson, env, +4 more.

get_addon_infoA

Get comprehensive information about a Heroku add-on. Use this tool when you need to: 1) View add-on details, 2) Check plan details and state, 3) View billing information. Accepts add-on ID, name, or attachment name.

Inputs: addon (required), app.

get_app_infoA

Get comprehensive information about a Heroku application. Use this tool when you need to: 1) View app configuration and settings, 2) Check dyno formation and scaling, 3) List add-ons and buildpacks, 4) View collaborators and access details, 5) Check domains and certificates. Accepts app name and optional JSON format. Returns detailed app status and configuration.

Inputs: app (required), json.

get_app_logsA

View application logs with flexible filtering options. Use this tool when you need to: 1) Monitor application activity in real-time, 2) Debug issues by viewing recent logs, 3) Filter logs by dyno, process type, or source.

Inputs: app (required), dynoName, processType, source.

list_addon_plansA

List available plans for a specific Heroku add-on service. Use this tool when you need to: 1) View all plans for a service, 2) Compare plan pricing, 3) Check plan availability. Requires add-on service slug and returns detailed plan information.

Inputs: service (required), json.

list_addonsA

List Heroku add-ons with flexible filtering options. Use this tool when you need to: 1) View all add-ons across your apps, 2) List add-ons for a specific app, 3) Get detailed add-on metadata in JSON format.

Inputs: all, app, json.

list_addon_servicesA

List available Heroku add-on services. Use this tool when you need to view all available add-on services. Returns a list of add-on services with their basic information.

Inputs: json.

list_appsA

List Heroku applications with flexible filtering options. Use this tool when you need to: 1) Show all apps owned by the user, 2) Show apps where the user is a collaborator (use all=true), 3) Filter apps by team or private space. Note: For checking app name availability, prefer using get_app_info as it returns a more focused dataset. The response includes app names, regions, and ownership information.

Inputs: all, json, personal, space, +1 more.

list_private_spacesA

List Heroku Private Spaces available to the user. Use this tool when you need to: 1) View all private spaces, 2) Get space details like CIDR blocks and regions, 3) Check space compliance features, or 4) View space capacity information. Supports JSON output for detailed metadata. Essential for enterprise space management.

Inputs: json.

list_teamsA

List Heroku Teams the user belongs to. Use this tool when you need to: 1) View all accessible teams, 2) Check team membership, 3) Get team metadata and enterprise relationships, or 4) Verify team access for app operations. Supports JSON output for detailed team information.

Inputs: json.

maintenance_offA

Disable maintenance mode for Heroku applications. Use this tool when you need to: 1) Restore normal application traffic routing, 2) Resume dyno operations after maintenance, 3) Complete deployment processes, 4) Verify application health after maintenance. The tool handles service restoration and process resumption.

Inputs: app (required).

maintenance_onA

Enable maintenance mode for Heroku applications. Use this tool when you need to: 1) Redirect traffic to a maintenance page, 2) Prepare for system updates or deployments, 3) Schedule planned maintenance windows, 4) Gracefully handle service interruptions. The tool manages traffic routing and process states while preserving running operations.

Inputs: app (required).

pg_backupsB

Manage database backup operations and schedules. Use this tool when you need to: 1) View existing database backups, 2) Monitor backup schedules and status, 3) Track backup operation progress, 4) Verify backup availability. The tool helps maintain database backup operations and disaster recovery readiness.

Inputs: app (required).

pg_credentialsA

Manage database access credentials and security. Use this tool when you need to: 1) View current database credentials, 2) Configure database access permissions, 3) Rotate credentials for security compliance, 4) Set up monitoring access. The tool helps maintain secure database access and credential management.

Inputs: app (required), database.

pg_infoA

Display detailed information about Heroku PostgreSQL databases. Use this tool when you need to: 1) View comprehensive database configuration and status, 2) Monitor database performance metrics, 3) Check connection and resource utilization, 4) Assess database health and capacity. The tool provides detailed insights into database operations and configuration.

Inputs: app (required), database.

pg_killA

Terminate specific database processes. Use this tool when you need to: 1) Stop problematic or stuck queries, 2) Clear blocking transactions, 3) Manage resource-intensive operations, 4) Handle runaway processes safely. The tool provides controlled process termination with optional force mode.

Inputs: app (required), pid (required), database, force.

pg_locksA

Analyze database locks and blocking transactions. Use this tool when you need to: 1) Identify blocked queries and lock chains, 2) Investigate deadlock situations, 3) Monitor transaction lock states, 4) Resolve blocking issues affecting performance. The tool helps diagnose and resolve database concurrency problems.

Inputs: app (required), database, truncate.

pg_maintenanceA

Monitor database maintenance status and operations. Use this tool when you need to: 1) Check current maintenance windows, 2) View scheduled maintenance activities, 3) Track maintenance operation progress, 4) Plan database maintenance tasks. The tool provides visibility into database maintenance state and scheduling.

Inputs: app (required), database.

pg_outliersB

Identify resource-intensive database operations. Use this tool when you need to: 1) Find slow or expensive queries, 2) Analyze query performance patterns, 3) Optimize database workload, 4) Track query statistics over time. The tool helps identify opportunities for performance optimization.

Inputs: app (required), database, num, reset, +1 more.

pg_psA

Monitor active database queries and processes. Use this tool when you need to: 1) View currently executing queries, 2) Track query progress and resource usage, 3) Identify long-running or blocked queries, 4) Debug performance issues in real-time. The tool provides detailed visibility into database activity with optional verbose output.

Inputs: app (required), database, verbose.

pg_psqlA

Execute SQL queries against Heroku PostgreSQL databases. Use this tool when you need to: 1) Run SQL queries for database analysis, 2) Investigate database locks and performance, 3) Make schema modifications or updates, 4) Execute complex database operations. The tool provides direct SQL access with support for file-based queries and credential management.

Inputs: app (required), command, credential, database, +1 more.

pg_upgradeA

Upgrade PostgreSQL database version. Use this tool when you need to: 1) Migrate to a newer PostgreSQL version, 2) Plan version upgrade paths, 3) Execute controlled version migrations, 4) Verify upgrade compatibility. The tool manages safe database version upgrades with confirmation protection.

Inputs: app (required), confirm, database, version.

pipelines_createA

Create new Heroku deployment pipelines. Use this tool when you need to: 1) Set up new deployment workflows, 2) Create staged application environments, 3) Organize apps by development stages, 4) Configure team-based pipeline structures. The tool manages pipeline creation with optional team and initial app configuration.

Inputs: name (required), stage (required), app, team.

pipelines_infoA

Display detailed pipeline configuration. Use this tool when you need to: 1) View pipeline stage configuration, 2) Check connected applications, 3) Verify pipeline settings, 4) Monitor pipeline status. The tool provides comprehensive pipeline information and structure details.

Inputs: pipeline (required), json.

pipelines_listA

View available Heroku pipelines. Use this tool when you need to: 1) List accessible pipelines, 2) Check pipeline ownership and access, 3) View pipeline organization, 4) Find specific pipeline configurations. The tool provides pipeline visibility with optional JSON output format.

Inputs: json.

pipelines_promoteA

Promote applications through pipeline stages. Use this tool when you need to: 1) Deploy code to staging or production environments, 2) Manage staged releases, 3) Coordinate multi-app promotions, 4) Control deployment workflows. The tool handles safe promotion of apps between pipeline stages.

Inputs: app (required), to.

ps_listA

List and monitor Heroku application dynos. Use this tool when you need to: 1) View all running dynos for an app, 2) Check dyno status and health, 3) Monitor application process states, 4) Verify dyno configurations. The tool provides process visibility with optional JSON output format.

Inputs: app (required), json.

ps_restartA

Restart Heroku application processes. Use this tool when you need to: 1) Restart specific dynos by name, 2) Restart all dynos of a process type, 3) Perform full application restarts, 4) Reset dyno states selectively. The tool manages process restarts with flexible targeting options.

Inputs: app (required), dyno-name, process-type.

ps_scaleA

Scale and resize Heroku application dynos. Use this tool when you need to: 1) Adjust dyno quantities up or down, 2) Change dyno sizes for performance, 3) View current formation details, 4) Manage resource allocation. The tool handles dyno scaling with support for type-specific adjustments.

Inputs: app (required), dyno.

rename_appA

Rename an existing Heroku application. Use this tool when a user needs to: 1) Change an app's name, or 2) Resolve naming conflicts. Requires both current app name and desired new name. The tool validates name availability and handles the rename process.

Inputs: app (required), newName (required).

transfer_appA

Transfer ownership of a Heroku application. Use this tool when a user wants to: 1) Transfer an app to another user's account, 2) Move an app to a team, 3) Change app ownership for organizational purposes. Requires the app name and recipient (email for users, name for teams). The current user must be the app owner or a team admin to perform the transfer.

Inputs: app (required), recipient (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources and actions, such as create_app vs. get_app_info. However, some PostgreSQL tools like pg_ps and pg_outliers have overlapping monitoring functions that could cause confusion, though their descriptions help differentiate them.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun or noun_verb pattern throughout, such as create_addon, list_addons, pg_backups, and ps_scale. All use snake_case uniformly, with clear prefixes like 'pg_' for PostgreSQL and 'ps_' for process-related tools, making the naming predictable and readable.

    Tool Count3/5

    With 33 tools, the count is high and may feel heavy for the Heroku domain, as it includes many specialized PostgreSQL tools that could be consolidated. While comprehensive, it borders on being overwhelming compared to typical well-scoped servers (3-15 tools), though it covers a broad range of operations.

    Completeness5/5

    The tool set provides complete CRUD and lifecycle coverage for Heroku's core domains, including apps, add-ons, PostgreSQL, pipelines, and processes. It handles creation, retrieval, updates, deletion, and management operations across all areas, with no obvious gaps that would cause agent failures.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides comprehensive Heroku application management through the Heroku Platform API for AI assistants using the Model Context Protocol. It enables users to scale dynos, view deployment history, access logs, and manage environment variables through natural language.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and MCP clients to execute commands, copy/move files, manage background jobs and port forwarding, and optionally view and control remote screens using scoped, expiring agent tokens.
      6 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to create projects, deploy files, container images, or Git repositories, attach domains, set write-only secrets, add Postgres, read logs, metrics, and failure summaries, and roll back.
      Apache 2.0