Heroku MCP server for AI agents

The Heroku Platform MCP Server is a specialized implementation of the Model Context Protocol that enables large language models to interact with Heroku Platform resources. It provides tools for managing apps, dynos, add-ons, and other Heroku resources through natural language commands.

Installation and Setup

Authentication

Before using the MCP server, you need to generate a Heroku authorization token:

heroku authorizations:create

Alternatively, you can use an existing token:

heroku auth:token

You can also create a token through the Heroku Dashboard by going to Account Settings > Applications > Create authorization.

Deploying on Heroku

The simplest way to deploy the server is using the Heroku Deploy button available at https://www.herokucdn.com/deploy/button.svg, which will deploy directly from the template at https://github.com/heroku/heroku-mcp-server.

Configuration

Claude Desktop

Add this to your claude_desktop_config.json:

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

Zed

Add this 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 either of these options to your Cursor mcp.json:

Simple form:

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

Explicit form:

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

Windsurf

Add this to your Windsurf mcp_config.json:

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

Cline

Add this to your Cline config.json:

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

VSCode

Add this to your VSCode settings.json or .vscode/mcp.json:

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

Trae

Add this to your Trae mcp_settings.json:

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

Via Smithery

To install via Smithery:

npx -y @smithery/cli install @heroku/heroku-mcp-server --client claude

Available Tools

Application Management

list_apps - List all Heroku apps with filtering options
get_app_info - Get detailed information about an app
create_app - Create a new app with customizable settings
rename_app - Rename an existing app
transfer_app - Transfer ownership of an app
deploy_to_heroku - Deploy projects to Heroku
deploy_one_off_dyno - Execute code in a sandboxed environment

Process & Dyno Management

ps_list - List all dynos for an app
ps_scale - Scale dynos up or down
ps_restart - Restart dynos

Add-ons

list_addons - List all add-ons
get_addon_info - Get add-on details
create_addon - Provision a new add-on

Maintenance & Logs

maintenance_on - Enable maintenance mode
maintenance_off - Disable maintenance mode
get_app_logs - View application logs

Pipeline Management

pipelines_create - Create a new pipeline
pipelines_promote - Promote apps to next stage
pipelines_list - List available pipelines
pipelines_info - Get pipeline details

Team & Space Management

list_teams - List your teams
list_private_spaces - List available spaces

PostgreSQL Database Management

pg_psql - Execute SQL queries
pg_info - Display database information
pg_ps - View active queries
pg_locks - View database locks
pg_outliers - Identify resource-intensive queries
pg_credentials - Manage database credentials
pg_kill - Terminate database processes
pg_maintenance - Show maintenance information
pg_backups - Manage database backups
pg_upgrade - Upgrade PostgreSQL

Environment Variables

The server supports these environment variables:

HEROKU_API_KEY: Your Heroku authorization token (required)
MCP_SERVER_REQUEST_TIMEOUT: Timeout for command execution in milliseconds (default: 15000)

Example 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"
      }
    }
  }
}

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.