Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Node.js Behavior in Heroku
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • AI
  • Working with AI
  • Heroku Platform MCP Server

Heroku Platform MCP Server

Last updated April 22, 2025

Table of Contents

  • Use Cases and Benefits
  • How It Works
  • Authentication
  • Configure the Heroku MCP Server
  • Available Tools
  • Debugging
  • Additional Reading

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.

The Heroku Platform MCP Server is a specialized Model Context Protocol (MCP) implementation designed to facilitate 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. With this implementation, AI-powered applications like Claude Desktop, Cursor, and Windsurf can directly interface with Heroku.

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.

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
  • Use your Heroku Dashboard:
    1. Click your avatar, then select Account Settings.
    2. Open the Applications tab.
    3. Next to Authorizations, click Create authorization.

Copy the token and use it as your HEROKU_API_KEY to configure the Heroku MCP Server.

Configure the Heroku MCP Server

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

Claude Desktop

Add this snippet to your claude_desktop_config.json:

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

Zed

Add this snippet to your Zed settings.json:

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

Cursor

Add this snippet to your Cursor mcp.json:

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

Windsurf

Add this snippet to your Windsurf mcp_config.json:

{
  "mcpServers": {
    "heroku": {
      "command": "npx -y @heroku/mcp-server",
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_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.

  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 with Cmd/Ctrl + Shift + P.
    • Type Preferences: Open User Settings (JSON).
    • Add this snippet: json { "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.

The debugger automatically builds your TypeScript files before launching.

Additional Reading

  • GitHub repo
  • Heroku CLI
  • Heroku CLI Commands

Keep reading

  • Working with AI

Feedback

Log in to submit feedback.

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices