Deployhq

DeployHQ MCP Server

用于 DeployHQ 的模型上下文协议（MCP）服务，可让 Claude Desktop 和 Claude Code 等 AI 助手与您的 DeployHQ 部署交互。

🚀 功能

• 全面集成 DeployHQ API：访问项目、服务器和部署
• 轻松安装：直接使用 npx，无需安装
• 兼容 Claude Desktop 和 Claude Code：为这两种 MCP 客户端提供 stdio 传输
• 安全：通过环境变量提供凭据，绝不存储
• 类型安全：使用 TypeScript 构建，并通过 Zod 进行验证
• 多种传输方式：stdio（主要方式）、SSE 和 HTTP（可选，用于托管）
• 可用于生产环境：提供全面的错误处理和日志记录

📋 可用工具

MCP 服务为 AI 助手提供 18 种工具：

工具	描述	参数
list_projects	列出所有项目	无
get_project	获取项目详情	permalink
list_servers	列出项目服务器	project
list_deployments	分页列出部署	project、page?、server_uuid?
get_deployment	获取部署详情	project、uuid
get_deployment_log	获取部署日志输出	project、uuid
create_deployment	创建新部署	project、parent_identifier、start_revision、end_revision，以及可选参数
list_ssh_keys	列出所有 SSH 公钥	无
create_ssh_key	创建新的 SSH 密钥对	title、key_type?
list_global_environment_variables	列出所有全局环境变量	无
create_global_environment_variable	创建全局环境变量	name、value、locked?、build_pipeline?
update_global_environment_variable	更新全局环境变量	id、name?、value?、locked?、build_pipeline?
delete_global_environment_variable	删除全局环境变量	id
list_global_config_files	列出所有全局配置文件模板	无
get_global_config_file	获取包含正文的全局配置文件	id
create_global_config_file	创建全局配置文件模板	path、body、description?、build?
update_global_config_file	更新全局配置文件模板	id、path?、body?、description?、build?
delete_global_config_file	删除全局配置文件模板	id

list_projects

列出 DeployHQ 账户中的所有项目。

返回：包含仓库信息和部署状态的项目数组。

get_project

获取特定项目的详细信息。

参数：

• permalink（字符串）：项目固定链接或标识符

list_servers

列出为项目配置的所有服务器。

参数：

• project（字符串）：项目固定链接

list_deployments

列出项目的部署，并支持分页。

参数：

• project（字符串）：项目固定链接
• page（数字，可选）：分页页码
• server_uuid（字符串，可选）：按服务器 UUID 筛选

get_deployment

获取特定部署的详细信息。

参数：

• project（字符串）：项目固定链接
• uuid（字符串）：部署 UUID

get_deployment_log

获取特定部署的部署日志，适用于调试失败的部署。

参数：

• project（字符串）：项目固定链接
• uuid（字符串）：部署 UUID

返回：完整的部署日志文本

create_deployment

为项目创建新的部署。

参数：

• project (string)：项目永久链接
• parent_identifier (string)：服务器或服务器组 UUID
• start_revision (string)：起始提交哈希
• end_revision (string)：结束提交哈希
• branch (string, optional)：要部署的分支
• mode (string, optional)："queue" 或 "preview"
• copy_config_files (boolean, optional)：复制配置文件
• run_build_commands (boolean, optional)：运行构建命令
• use_build_cache (boolean, optional)：使用构建缓存
• use_latest (string, optional)：使用最近部署的提交作为起点

list_ssh_keys

列出账户的所有 SSH 公钥。

返回：SSH 密钥数组，包含公钥、指纹和密钥类型。绝不返回私钥。

create_ssh_key

为账户创建新的 SSH 密钥对。

参数：

• title (string)：SSH 密钥的标题
• key_type (string, optional)：密钥类型 — ED25519（默认）或 RSA

list_global_environment_variables

列出所有全局（账户级）环境变量。

返回：环境变量数组，包含名称、已隐藏的值和设置。

create_global_environment_variable

创建新的全局环境变量，供所有项目使用。

参数：

• name (string)：变量名称
• value (string)：变量值
• locked (boolean, optional)：锁定变量以防止更改
• build_pipeline (boolean, optional)：使变量可用于构建流水线

update_global_environment_variable

更新现有的全局环境变量。

参数：

• id (string)：环境变量标识符
• name (string, optional)：变量名称
• value (string, optional)：变量值
• locked (boolean, optional)：锁定状态
• build_pipeline (boolean, optional)：是否可用于构建流水线

delete_global_environment_variable

删除全局环境变量。此操作不可撤销。

参数：

• id (string)：环境变量标识符

list_global_config_files

列出所有全局（账户级）配置文件模板。

返回：配置文件数组，包含路径、描述和设置。

get_global_config_file

获取指定的全局配置文件模板，包括其正文内容。

参数：

• id (string)：配置文件标识符（UUID）

create_global_config_file

创建新的全局配置文件模板。

参数：

• path (string)：文件路径（例如 config/database.yml）
• body (string)：文件内容
• description (string, optional)：配置文件说明
• build (boolean, optional)：与构建流水线配合使用

update_global_config_file

更新现有的全局配置文件模板。

参数：

• id (string)：配置文件标识符（UUID）
• path (string, optional)：文件路径
• body (string, optional)：文件内容
• description (string, optional)：说明
• build (boolean, optional)：构建流水线标记

delete_global_config_file

删除全局配置文件模板。此操作不可撤销。

参数：

• id (string)：配置文件标识符（UUID）

🚀 快速开始

使用 Claude Code 轻松安装

为 Claude Code 安装的最快方式：

claude mcp add --transport stdio deployhq --env [email protected] --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server

将 [email protected]、your-api-key 和 your-account 替换为你实际的 DeployHQ 凭据。

手动配置（适用于 Claude Desktop 和 Claude Code）

两个客户端使用相同的配置。从 docs/claude-config.json 复制配置并添加你的凭据。

Claude Desktop：

编辑你的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

然后重启 Claude Desktop。

Claude Code：

将配置添加到项目目录中的 .claude.json 文件，然后退出并重启 Claude 会话（输入 exit 或按 Ctrl+D，然后运行 claude）。

配置：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
        // Optional: "LOG_LEVEL": "INFO"  (ERROR, INFO, or DEBUG)
      }
    }
  }
}

注意：只需要 3 个 DeployHQ 凭据。LOG_LEVEL 为可选项，默认值为 INFO。

开始使用

完成配置后，你可以让 Claude 与 DeployHQ 交互：

• “列出我所有的 DeployHQ 项目”
• “显示项目 X 的服务器”
• “获取项目 Y 的最新部署状态”
• “为项目 Z 创建新部署”
• “显示最新部署的部署日志”
• “列出我的全局环境变量”
• “为 database.yml 创建全局配置文件模板”
• “显示我的 SSH 密钥”

💡 常见用法示例

检查部署状态

User: What's the status of my latest deployment for my-app?
Claude: [Uses list_deployments → get_deployment → shows status]

调试失败的部署

User: Why did the last deployment fail for my-app?
Claude: [Uses list_deployments → get_deployment_log → analyzes log]

部署最新更改

User: Deploy the latest changes to production for my-app
Claude: [Uses list_servers → list_deployments → create_deployment with use_latest]

完整工作流示例

User: I want to deploy my-app to production with the latest changes

Claude will:
1. Use list_projects to find "my-app"
2. Use list_servers to find production server UUID
3. Use list_deployments with use_latest to get last revision
4. Use create_deployment to queue deployment
5. Use get_deployment to show status
6. Use get_deployment_log if anything fails

🔧 配置选项

环境变量

必需

• DEPLOYHQ_EMAIL：你的 DeployHQ 登录邮箱
• DEPLOYHQ_API_KEY：你的 DeployHQ 密码/API 密钥
• DEPLOYHQ_ACCOUNT：你的 DeployHQ 帐户名称（来自 URL：https://ACCOUNT.deployhq.com）

可选

• LOG_LEVEL：控制日志详细程度 - ERROR、INFO 或 DEBUG（默认值：INFO）
• NODE_ENV：环境模式 - production 或 development
• DEPLOYHQ_READ_ONLY：设置为 true 可阻止所有更改操作（默认值：false）

日志级别

使用 LOG_LEVEL 环境变量控制日志详细程度：

• ERROR：仅显示错误
• INFO：显示信息和错误（默认）
• DEBUG：显示所有日志，包括详细的 API 调用

示例：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

🐛 故障排除

服务无法启动

问题：服务启动后立即退出

解决方案：

• 检查是否已设置所有必需的环境变量
• 确认 Node.js 版本为 18 或更高版本：node --version
• 检查 Claude Desktop/Code 中的日志，查看错误消息
• 尝试设置 LOG_LEVEL=DEBUG 以查看更多详情

身份验证错误

问题：“Authentication failed”或 401/403 错误

解决方案：

• 确认邮箱和 API 密钥正确无误
• 检查 API 密钥是否已过期
• 确保你的帐户已启用 API 访问权限
• 尝试使用相同的凭据登录 DeployHQ 网页界面

未找到项目

问题：“Project not found”或 404 错误

解决方案：

• 使用 list_projects 查看准确的永久链接格式
• 项目永久链接区分大小写
• 检查你是否有权访问 DeployHQ 中的该项目

部署创建被阻止

问题：尝试创建部署时出现“Server is running in read-only mode”错误

解决方案：

• 默认情况下会禁用只读模式，但你可能已将其启用
• 要禁用只读模式，请在环境变量中设置 DEPLOYHQ_READ_ONLY=false
• 或使用 --read-only=false CLI 标志
• 有关只读模式的详细说明，请参阅安全性部分

部署失败

问题：部署已创建，但立即失败

解决方案：

• 使用 get_deployment_log 查看详细的错误日志
• 使用 list_servers 确认服务器 UUID 正确无误
• 检查仓库中是否存在起始修订版本和结束修订版本
• 确保服务器已配置正确的部署密钥

连接超时

问题：出现“Request timeout”错误

解决方案：

• 检查你的互联网连接
• 确认 DeployHQ API 可以访问：curl https://YOUR_ACCOUNT.deployhq.com
• 部署列表较大时可能需要较长时间 - 请使用分页
• 如果 DeployHQ 遇到问题，请稍后重试

日志未显示

问题：看不到任何日志输出

解决方案：

• 对于 stdio 传输，日志会输出到 stderr，而不是 stdout
• 检查 Claude Desktop/Code 日志位置：
  • macOS：~/Library/Logs/Claude/
  • Windows：%APPDATA%\Claude\logs\
• 设置 LOG_LEVEL=DEBUG 以输出详细日志
• 对于托管模式，请检查 Digital Ocean 日志

获取 DeployHQ 凭据

1. 用户名：你的 DeployHQ 登录邮箱
2. 密码：你的 DeployHQ 密码
3. 账户：你的 DeployHQ 账户名称（可在 URL 中查看：https://ACCOUNT.deployhq.com）

🏗️ 架构

┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  or Claude Code │◄──────────────────►│  API        │
│                 │    (via npx)       │             │
│  Environment    │                    │             │
│  Variables ─────┼───────────────────►│ Basic Auth  │
└─────────────────┘                    └─────────────┘

• Claude Desktop/Code：通过 npx 启动服务的 MCP 客户端
• MCP 服务：从环境变量读取凭据，通过 stdio 通信
• DeployHQ API：使用 HTTP Basic Authentication 的 REST API

📦 前提条件

• Node.js 18+（推荐 Node 20+）
• 具有 API 访问权限的 DeployHQ 账户（所有付费套餐均提供）

注意：该服务使用 node-fetch 发送 HTTP 请求。开发工具（ESLint、Vitest）需要 Node 18+。

🔧 本地开发

1. 克隆仓库

git clone https://github.com/your-username/deployhq-mcp-server.git
cd deployhq-mcp-server

2. 安装依赖项

npm install

3. 运行测试

npm test              # Run tests once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run test:ui       # Run tests with UI

4. 构建项目

npm run build

5. 在本地测试 stdio 传输

# Build first
npm run build

# Test with environment variables
DEPLOYHQ_EMAIL="[email protected]" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js

服务将以 stdio 模式启动，并等待 stdin 上的 JSON-RPC 消息。

6. 使用 Claude Code 进行测试

配置本地 .claude.json 以使用构建版本：

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}

🧪 测试

项目使用 Vitest，包含一套全面的测试：

测试覆盖范围：

• ✅ 工具架构验证 - 全部 18 个 MCP 工具架构，涵盖有效和无效输入
• ✅ API 客户端方法 - 全部 DeployHQ API 方法，使用模拟响应
• ✅ 错误处理 - 身份验证、验证和网络错误
• ✅ MCP 服务工厂 - 服务创建和配置

运行测试：

npm test              # Run all tests
npm run test:watch    # Watch mode for development
npm run test:coverage # Generate coverage report
npm run test:ui       # Interactive UI for debugging

测试统计：

• 10 个测试套件，共 216 项测试
• 覆盖 tools、api-client 和 mcp-server 模块
• 使用模拟的 fetch 进行隔离的单元测试

🔒 安全性

只读模式（可选）

默认情况下，MCP 服务允许所有操作，包括创建部署。 这是大多数用户推荐的配置。

如果你希望进一步防止意外部署，可以启用服务内置的可选只读模式，以阻止创建部署。

默认行为（无需配置）：

• ✅ 默认允许部署
• ✅ 所有操作均可使用：列出、获取和创建部署
• ✅ 开箱即用，功能完整

你可能希望启用只读模式的情况：

• 你希望额外防止通过 AI 意外部署
• 你连接到生产环境，并希望增加一层安全防护
• 你只需要读取权限来监控部署
• 你仍在测试集成，希望谨慎操作

重要提示：只读模式完全可选。即使不启用该模式，服务也能完整运行。

如何启用只读模式：

通过环境变量：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account",
        "DEPLOYHQ_READ_ONLY": "true"
      }
    }
  }
}

通过 CLI 标志：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": [
        "-y",
        "deployhq-mcp-server",
        "--read-only"
      ],
      "env": {
        "DEPLOYHQ_EMAIL": "[email protected]",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

配置优先级：

1. CLI 标志 --read-only（优先级最高）
2. 环境变量 DEPLOYHQ_READ_ONLY
3. 默认值：false（允许部署）

其他安全说明

• 部署日志可能包含机密信息：部署日志可能包含环境变量、API 密钥和其他敏感信息。使用获取日志的工具时请谨慎，尤其是涉及第三方 AI 服务时。

• 使用遵循最小权限原则的 API 密钥：创建专用 API 密钥，并仅授予 MCP 访问所需的最低权限。考虑为只读操作和读写操作分别使用不同的密钥。

• 审计 MCP 活动：监控 MCP 使用情况，尤其是在生产环境中。定期查看日志，留意异常行为。

• 环境变量：凭据不会被存储，只会通过环境变量传递。

• HTTPS：使用 npx 时，凭据会保留在本机。

• 无遥测：除直接发送至 DeployHQ API 外，不会向任何地方发送数据。

---

🌐 可选：托管部署

此服务也可以部署为使用 SSE/HTTP 传输的托管服务。这适用于 Web 集成或团队共享访问。

🚀 部署到 Digital Ocean

选项 1：使用控制面板

1. 准备代码库：

   git add .
   git commit -m "Initial commit"
   git push origin main
   

2. 创建新应用：

   • 前往 Digital Ocean Apps
   • 点击“Create App”
   • 选择你的 GitHub 代码库
   • 选择分支（main）

3. 配置应用：

   • Digital Ocean 会自动检测 Dockerfile
   • 或使用 .do/app.yaml 配置

4. 设置环境变量：

   • 前往 App Settings → Environment Variables
   • 添加以下加密变量：
     • DEPLOYHQ_EMAIL
     • DEPLOYHQ_API_KEY
     • DEPLOYHQ_ACCOUNT
   • 添加以下普通变量：
     • NODE_ENV=production
     • PORT=8080
     • LOG_LEVEL=info

5. 部署：

   • 点击“Next”和“Create Resources”
   • 等待部署完成

6. 配置自定义域名（可选）：

   • 前往 Settings → Domains
   • 添加 mcp.deployhq.com
   • 按照说明更新 DNS 记录

选项 2：使用 doctl CLI

1. 安装 doctl：

   # macOS
   brew install doctl
   
   # Linux
   cd ~
   wget https://github.com/digitalocean/doctl/releases/download/v1.104.0/doctl-1.104.0-linux-amd64.tar.gz
   tar xf doctl-1.104.0-linux-amd64.tar.gz
   sudo mv doctl /usr/local/bin
   

2. 进行身份验证：

   doctl auth init
   

3. 更新 .do/app.yaml：

   • 编辑 github.repo 字段，填写你的代码库
   • 查看并按需调整实例规格

4. 创建应用：

   doctl apps create --spec .do/app.yaml
   

5. 设置环境机密：

   # Get your app ID
   doctl apps list
   
   # Update environment variables (replace APP_ID)
   doctl apps update APP_ID --spec .do/app.yaml
   

6. 查看日志：

   doctl apps logs APP_ID --follow
   

🔒 托管安全

• 切勿提交凭据：本地开发时使用 .env（已由 .gitignore 排除）
• 使用 Digital Ocean 机密：将凭据存储为加密环境变量
• 仅使用 HTTPS：Digital Ocean 会自动提供 HTTPS
• 最小权限：使用专用 DeployHQ 用户，并仅授予所需的最低权限

📊 托管监控

健康检查

托管服务在 /health 提供健康检查端点：

curl https://mcp.deployhq.com/health

日志

在 Digital Ocean 中查看日志：

• 控制面板：前往你的应用 → Runtime Logs
• CLI：doctl apps logs <APP_ID> --follow

警报

Digital Ocean 会针对以下情况发出警报：

• 部署失败
• 域名配置问题
• 健康检查失败

🧪 测试托管服务

测试 SSE 端点：

curl -N http://localhost:8080/sse \
  -H "X-DeployHQ-Email: [email protected]" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account"

测试 HTTP 传输端点：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-DeployHQ-Email: [email protected]" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

完整的测试示例请参阅托管部署文档。

📚 项目结构

deployhq-mcp-server/
├── src/
│   ├── stdio.ts          # stdio transport entrypoint (for Claude Desktop/Code)
│   ├── index.ts          # Express server (for hosted deployment)
│   ├── mcp-server.ts     # Core MCP server factory (shared)
│   ├── tools.ts          # Tool definitions and schemas (shared)
│   ├── api-client.ts     # DeployHQ API client (shared)
│   ├── transports/       # SSE/HTTP handlers (for hosted)
│   └── utils/            # Logging and utilities
├── docs/
│   ├── claude-config.json          # Universal config template (Desktop & Code)
│   ├── USER_GUIDE.md               # User documentation
│   ├── DEPLOYMENT.md               # Hosted deployment guide
│   └── HTTP_TRANSPORT.md           # HTTP transport documentation
├── .do/
│   └── app.yaml          # Digital Ocean configuration (optional)
├── Dockerfile            # Container configuration (optional)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── STDIO_MIGRATION.md    # stdio migration documentation
└── README.md             # This file

🤝 参与贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此代码库
2. 创建功能分支
3. 进行修改
4. 视情况添加测试
5. 提交 pull request

维护者须知

创建版本并发布到 npm 的说明，请参阅 RELEASING.md。

隐私政策

此 MCP 服务不会收集、存储或传输任何用户数据，除非这些数据是与 DeployHQ API 通信所必需的。凭据通过环境变量传递，绝不会记录到日志或持久化存储。

DeployHQ 的完整隐私政策请见：https://www.deployhq.com/privacy

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件

🆘 支持

• DeployHQ API 文档：https://www.deployhq.com/support/api
• MCP 文档：https://modelcontextprotocol.io
• 问题反馈：https://github.com/deployhq/deployhq-mcp-server/issues

🔗 相关链接

• DeployHQ
• Model Context Protocol
• Digital Ocean App Platform
• Claude Desktop
• Claude Code CLI