Heroku MCP server

The Heroku Platform MCP Server enables large language models to interact directly with Heroku resources through a Model Context Protocol (MCP) implementation, allowing LLMs to read, manage, and operate Heroku Platform resources with natural language interfaces.

Authentication

Generate a Heroku authorization token using one of these methods:

heroku authorizations:create

Or retrieve an existing token:

heroku auth:token

You can also create a token through the Heroku Dashboard by:

1. Selecting your avatar, then Account Settings
2. Opening the Applications tab
3. Clicking Create authorization next to Authorizations

Configuration

Claude Desktop

Add this snippet to your claude_desktop_config.json:

{
  "mcpServers": {
    "heroku": {
      "command": {
        "path": "npx",
        "args": ["-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": {
        "path": "npx",
        "args": ["-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": {
        "path": "npx",
        "args": ["-y", "@heroku/mcp-server"]
      },
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Cline

Add this snippet to your Cline config.json:

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

VSCode

Add this snippet 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 snippet to your Trae mcp_settings.json:

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

Available Tools

Application Management

• list_apps - List all Heroku apps with filtering options
• get_app_info - Get detailed app information
• create_app - Create a new app with customizable settings
• rename_app - Rename an existing app
• transfer_app - Transfer app ownership
• deploy_to_heroku - Deploy projects to Heroku with configuration
• 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/down or resize them
• ps_restart - Restart specific dynos or processes

Add-ons

• list_addons - List all add-ons
• get_addon_info - Get detailed add-on information
• 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 the next stage
• pipelines_list - List available pipelines
• pipelines_info - Get detailed pipeline information

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 access
• pg_kill - Terminate specific processes
• pg_maintenance - Show maintenance information
• pg_backups - Manage database backups
• pg_upgrade - Upgrade PostgreSQL

Debugging

You can debug the server using the MCP inspector:

npx @modelcontextprotocol/inspector heroku-mcp-server

Or when developing locally:

cd /path/to/servers
npx @modelcontextprotocol/inspector dist/index.js

For VS Code debugging with breakpoints:

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

   {
     "heroku.mcp.authToken": "your-token-here"
   }
   

2. Use the Run and Debug launcher with the "MCP Server Launcher" configuration.

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.