heroku-mcp-server

heroku-mcp-server

Heroku Platform MCP 服务适用于 Common Runtime、Cedar Private 和 Shield Spaces，以及 Fir Private Spaces。

前提条件

• 必须在系统上全局安装 Heroku CLI，版本为 10.8.1 或更高。
  • 安装或升级 Heroku CLI

在 Heroku 上部署

概述

Heroku Platform MCP 服务是一种专用的模型上下文协议（MCP）实现，旨在促进 大模型（LLM）与 Heroku Platform 之间的无缝交互。此服务提供了一套可靠的 工具和功能，让大模型能够读取、管理和操作 Heroku Platform 资源。

主要功能：

• 通过由大模型驱动的工具直接与 Heroku Platform 资源交互
• 借助 Heroku CLI，安全地通过身份验证访问 Heroku Platform API
• 用于与 Heroku Platform 交互的自然语言界面

注意：Heroku Platform MCP 服务目前仍处于早期开发阶段。随着我们持续改进和完善 此实现，可用功能和工具可能会有所变化。欢迎提供反馈并参与贡献，共同塑造 此项目的未来。

注意：Heroku Platform MCP 服务要求 全局安装 Heroku CLI（v10.8.1+）。运行 heroku --version，确保安装了正确的版本。

配置 Heroku Platform MCP 服务

你可以配置 Claude Desktop、Zed、Cursor、Windsurf 和其他客户端，以便与 Heroku Platform MCP 服务配合使用。

使用 heroku mcp:start 配置 Heroku Platform MCP 服务

使用 heroku mcp:start 启动 Heroku Platform MCP 服务。我们推荐此方法，因为它会使用现有的 Heroku CLI 身份验证，因此你无需设置 HEROKU_API_KEY 环境变量。 heroku mcp:start 命令适用于 Heroku CLI 10.8.1 及更高版本。

使用 heroku mcp:start 进行配置有以下优势：

• 无需管理或公开 Heroku API 密钥
• 使用当前的 Heroku CLI 身份验证上下文
• 与受支持的客户端无缝配合

Claude Desktop 的配置示例：

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

Zed 的配置示例：

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

Cursor 的配置示例：

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

Windsurf 的配置示例：

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

Cline 的配置示例：

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

VSCode 的配置示例：

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

Trae 的配置示例：

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

**注意：**使用 heroku mcp:start 时，服务会通过当前的 Heroku CLI 会话进行身份验证，因此你 无需设置 HEROKU_API_KEY 环境变量。我们推荐使用 heroku mcp:start；但如果你更愿意 使用 API 密钥，可以采用下面的备用配置。

使用 npx -y @heroku/mcp-server 配置 Heroku Platform MCP 服务

你也可以使用 npx -y @heroku/mcp-server 命令启动 Heroku Platform MCP 服务。此方法要求你设置 HEROKU_API_KEY 环境 变量，并填入 Heroku 授权令牌。

生成 HEROKU_API_KEY

使用以下任一方法生成 Heroku 授权令牌：

• 使用 Heroku CLI 命令：

    heroku authorizations:create
  

• 使用 CLI 中已有的令牌

    heroku auth:token
  

  复制令牌，并在接下来的步骤中将其用作 HEROKU_API_KEY。

• 在 Heroku Dashboard 中：

  1. 选择你的头像，然后选择 Account Settings。
  2. 打开 Applications 选项卡。
  3. 在 Authorizations 旁边，点击 Create authorization。

Claude Desktop 的配置示例：

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

Zed 的配置示例：

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

Cursor 的配置示例：

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

Windsurf 的配置示例：

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

Cline 的配置示例：

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

VSCode 的配置示例：

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

Trae 的配置示例：

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

注意： 使用 npx -y @heroku/mcp-server 时，必须将 HEROKU_API_KEY 环境变量设置为你的 Heroku 授权令牌。

可用工具

应用管理

• list_apps - 列出所有 Heroku 应用。你可以按个人、协作者、团队或空间筛选应用。
• get_app_info - 获取应用的详细信息，包括其配置、dyno 和附加组件。
• create_app - 创建新应用，并自定义区域、团队和空间设置。
• rename_app - 重命名现有应用。
• transfer_app - 将应用所有权转移给其他用户或团队。
• deploy_to_heroku - 使用 app.json 配置将项目部署到 Heroku，支持团队部署、私有空间和环境设置。
• deploy_one_off_dyno - 在 Heroku 一次性 dyno 的沙盒环境中执行代码或命令。支持创建文件、网络访问、环境变量和自动清理。适合运行脚本、测试或临时工作负载。

进程与 Dyno 管理

• ps_list - 列出应用的所有 dyno。
• ps_scale - 增加或减少 dyno 数量，或调整 dyno 规格。
• ps_restart - 重启指定的 dyno、进程类型或所有 dyno。

附加组件

• list_addons - 列出所有应用或指定应用的所有附加组件。
• get_addon_info - 获取特定附加组件的详细信息。
• create_addon - 为应用配置新的附加组件。

维护与日志

• maintenance_on - 为应用启用维护模式。
• maintenance_off - 为应用禁用维护模式。
• get_app_logs - 查看应用日志。

流水线管理

• pipelines_create - 创建新的流水线。
• pipelines_promote - 将应用提升到流水线的下一阶段。
• pipelines_list - 列出可用的流水线。
• pipelines_info - 获取流水线的详细信息。

团队与空间管理

• list_teams - 列出你所属的团队。
• list_private_spaces - 列出可用的空间。

PostgreSQL 数据库管理

• pg_psql - 对 Heroku PostgreSQL 数据库执行 SQL 查询。
• pg_info - 显示数据库的详细信息。
• pg_ps - 查看活动查询及其执行详情。
• pg_locks - 查看数据库锁并识别阻塞事务。
• pg_outliers - 识别资源占用量高的查询。
• pg_credentials - 管理数据库凭据和访问权限。
• pg_kill - 终止指定的数据库进程。
• pg_maintenance - 显示数据库维护信息。
• pg_backups - 管理数据库备份和计划。
• pg_upgrade - 将 PostgreSQL 升级到较新版本。

调试

你可以使用 MCP 检查器或 VS Code 运行和调试功能来 运行和调试服务。

1. 在项目根目录运行 npm link，将项目链接为全局 CLI。
2. 使用 npm run build:dev 构建，或使用 npm run build:watch 监视文件更改并自动构建。

使用 MCP 检查器

在代码中未设置断点的情况下使用 MCP 检查器：

# Breakpoints are not available
npx @modelcontextprotocol/inspector heroku-mcp-server

或者，如果你已将软件包安装在特定目录中，或正在主动开发 Heroku MCP 服务：

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

使用 VS Code 运行和调试功能

使用 VS Code 运行和调试启动器，即可在代码中使用完整的断点功能：

1. 找到并选择运行调试项。
2. 在下拉菜单中选择标有 "MCP Server Launcher" 的配置。
3. 选择运行/调试按钮。

VS Code / Cursor 调试设置

要设置带断点的本地调试：

1. 将 Heroku 身份验证令牌存储在 VS Code 用户设置中：

   • 打开命令面板（Cmd/Ctrl + Shift + P）。
   • 输入 Preferences: Open User Settings (JSON)。
   • 添加以下代码片段：

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

2. 创建或更新 .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. 创建 .vscode/tasks.json：

   {
     "version": "2.0.0",
     "tasks": [
       {
         "type": "npm",
         "script": "build:watch",
         "group": {
           "kind": "build",
           "isDefault": true
         },
         "problemMatcher": ["$tsc"]
       }
     ]
   }
   

4. （可选）在 TypeScript 文件中设置断点。

5. 按 F5，或使用**Run and Debug**侧边栏。

注意：调试器会在启动前自动构建 TypeScript 文件。

环境变量

Heroku Platform MCP Server 支持以下环境变量：

HEROKU_API_KEY

你的 Heroku 授权令牌。用于通过 Heroku Platform 进行身份验证，且为必需项。

MCP_SERVER_REQUEST_TIMEOUT

命令执行的超时时间，单位为毫秒。如果未设置，默认值为 15000（15 秒）。

自定义超时时间的配置示例：

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