hatchbox

Hatchbox MCP 服务

适用于 Hatchbox 的 MCP 服务——让小型企业轻松托管 Rails。

概述

此 MCP 服务提供用于与 Hatchbox API 交互的工具，让你可以直接通过 AI 助手管理 Rails 应用的环境变量和部署。

主要功能

• 环境变量管理：
  • 查看所有环境变量（通过 SSH）
  • 获取指定环境变量（通过 SSH）
  • 设置和更新环境变量
  • 删除环境变量
• 部署控制：触发部署并检查其状态
• 安全功能：
  • 默认启用只读模式
  • 可配置部署权限
  • 通过基于 SSH 的安全访问读取环境变量
• 安全身份验证：使用 API 密钥和 SSH 密钥进行安全访问

安装

npm install hatchbox-mcp-server

配置

环境变量

必需变量

• HATCHBOX_API_KEY：用于身份验证的 Hatchbox API 密钥
• HATCHBOX_ACCOUNT_ID：你的 Hatchbox 账户 ID
• HATCHBOX_APP_ID：你的 Hatchbox 应用 ID
• HATCHBOX_DEPLOY_KEY：你的部署 Webhook 密钥

SSH 访问的可选变量

• WEB_SERVER_IP_ADDRESS：Hatchbox 服务的 IP 地址（启用 getEnvVars 和 getEnvVar 工具）
• SSH_KEY_PATH：SSH 私钥路径（默认为 ~/.ssh/id_rsa）
• HATCHBOX_APP_NAME：当服务上有多个应用时，用于筛选进程的应用名称（见下方示例）

安全配置

• READONLY：设为 false 以启用写入操作（默认值：true）
• ALLOW_DEPLOYS：设为 false 以禁用部署操作（默认值：true）

你可以在 Hatchbox 控制面板中找到这些值：

• API 密钥：账户设置
• 账户 ID：查看账户时显示在 URL 中
• 应用 ID：查看应用时显示在 URL 中
• 部署密钥：应用部署设置
• 服务 IP：服务的公共 IP 地址（用于 SSH 访问）

SSH 设置（可选——用于读取环境变量）

若要启用 getEnvVars 和 getEnvVar 工具，你需要通过 SSH 访问 Hatchbox 服务：

1. 将你的 SSH 公钥添加到 Hatchbox 服务上的 deploy 用户：

   ssh-copy-id deploy@your-server-ip
   

2. 测试 SSH 访问：

   ssh deploy@your-server-ip "echo 'SSH access working'"
   

3. 配置 MCP 服务，填入服务的 IP 地址（见下方配置）

同一服务上的多个应用

如果同一 Hatchbox 服务上运行着多个 Rails 应用，你需要指定 HATCHBOX_APP_NAME，以确定要读取哪个应用的环境变量：

# Example: If your server has multiple apps running
# App 1: mystore (running on port 3000)
# App 2: blog (running on port 3001)
# App 3: api (running on port 3002)

# To read env vars for the 'mystore' app:
HATCHBOX_APP_NAME=mystore

# To read env vars for the 'blog' app:
HATCHBOX_APP_NAME=blog

应用名称应与 Hatchbox 控制面板中显示的名称一致。此设置会筛选进程列表，找到特定应用对应的 puma 进程。

Claude Desktop 配置

将服务添加到 Claude Desktop 配置文件中：

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": ["-y", "hatchbox-mcp-server"],
      "env": {
        "HATCHBOX_API_KEY": "your-api-key-here",
        "HATCHBOX_ACCOUNT_ID": "1852",
        "HATCHBOX_APP_ID": "8540",
        "HATCHBOX_DEPLOY_KEY": "your-deploy-key-here",

        "// Optional - for SSH access to read env vars": "",
        "WEB_SERVER_IP_ADDRESS": "165.232.133.75",
        "SSH_KEY_PATH": "/Users/yourname/.ssh/id_rsa",
        "HATCHBOX_APP_NAME": "myapp",

        "// Optional - security settings": "",
        "READONLY": "false",
        "ALLOW_DEPLOYS": "true"
      }
    }
  }
}

工具

环境变量

getEnvVars

通过 SSH 从 Hatchbox 服务获取所有环境变量。

**要求：**必须配置 WEB_SERVER_IP_ADDRESS。

**参数：**无

示例：

"Show me all environment variables"

getEnvVar

通过 SSH 从 Hatchbox 服务获取指定环境变量。

**要求：**必须配置 WEB_SERVER_IP_ADDRESS。

参数：

• name（字符串，必需）：要获取的环境变量名称

示例：

{
  "name": "RAILS_ENV"
}

setEnvVar

设置或更新环境变量。

**要求：**READONLY 必须设为 false。

参数：

• name（字符串，必需）：环境变量名称
• value（字符串，必需）：环境变量值

示例：

{
  "name": "DATABASE_URL",
  "value": "postgres://user:pass@host:5432/dbname"
}

deleteEnvVars

删除一个或多个环境变量。

**要求：**必须将 READONLY 设置为 false。

参数：

• names（字符串数组，必填）：要删除的环境变量名称数组

示例：

{
  "names": ["OLD_VAR", "UNUSED_VAR"]
}

部署

triggerDeploy

为你的应用触发一次新部署。

**要求：**必须将 ALLOW_DEPLOYS 设置为 true（默认值）。

参数：

• sha（字符串，可选）：要部署的特定提交 SHA（未提供时使用最新提交）

示例：

{
  "sha": "abc123def456"
}

checkDeploy

检查部署状态。

**要求：**必须将 ALLOW_DEPLOYS 设置为 true（默认值）。

参数：

• activityId（字符串，必填）：由 triggerDeploy 返回的部署活动 ID

示例：

{
  "activityId": "12345"
}

使用示例

以下是一些可与 Claude 搭配使用的示例查询：

读取环境变量（需要 WEB_SERVER_IP_ADDRESS）

1. 查看所有环境变量： “显示所有环境变量”

2. 获取特定变量： “RAILS_ENV 的值是什么？”

写入环境变量（需要 READONLY=false）

3. 设置环境变量： “将 RAILS_ENV 设置为 production”

4. 删除环境变量： “删除 OLD_VAR 和 UNUSED_VAR 环境变量”

部署（需要 ALLOW_DEPLOYS=true）

5. 部署最新代码： “将最新提交部署到 Hatchbox”

6. 部署特定提交： “将提交 abc123def456 部署到 Hatchbox”

7. 检查部署状态： “检查部署活动 12345 的状态”

安全注意事项

API 安全

• 安全存储 API 密钥，切勿将其提交到版本控制系统
• 此服务只能访问你的 API 密钥有权访问的 Hatchbox 账户和应用

SSH 安全

• SSH 访问会暴露所有环境变量，包括机密信息
• 确保妥善保护 SSH 密钥
• 尽可能考虑使用专用的只读 SSH 密钥
• 仅在信任 MCP 客户端能够访问你的机密信息时，才配置 WEB_SERVER_IP_ADDRESS

权限模式

• **只读模式（默认）：**防止意外修改生产环境
• **部署控制：**可与写入操作分开禁用
• 根据安全要求配置权限：
  • 开发环境：READONLY=false、ALLOW_DEPLOYS=true
  • 预发布环境：READONLY=false、ALLOW_DEPLOYS=true
  • 生产环境：READONLY=true、ALLOW_DEPLOYS=false（推荐）
• 所有 API 通信均使用 HTTPS 加密

开发

此服务属于 PulseMCP 组织的 MCP 服务集合。有关开发说明和贡献指南，请参阅主仓库。

许可证

此项目采用 MIT 许可证。