部署HQ MCP服务器

DeployHQ的模型上下文协议（MCP）服务器，使Claude Desktop和Claude Code等AI助手能够与您的DeployHQ部署进行交互。

🚀 特性

全面部署HQ API集成：访问项目、服务器和部署
简易安装：直接与 npx -无需安装
适用于克劳德桌面和克劳德代码：MCP客户端的stdio传输
安全：通过环境变量的凭据，从不存储
类型安全：使用TypeScript和Zod验证构建
多个传输：stdio（主）、SSE和HTTP（主机可选）
生产就绪：全面的错误处理和记录

📋 可用工具

MCP服务器提供 18工具 对于AI助手：

工具	说明	参数
`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`	获取带有body的全局配置文件	`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 （string）：项目永久链接或标识符

`list_servers`

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

参数:

project （string）：项目永久链接

`list_deployments`

列出具有分页支持的项目的部署。

参数:

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

`get_deployment`

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

参数:

project （string）：项目永久链接
uuid （string）：部署UUID

`get_deployment_log`

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

参数:

project （string）：项目永久链接
uuid （string）：部署UUID

退货：以文本形式完成部署日志

`create_deployment`

为项目创建新部署。

参数:

project （string）：项目永久链接
parent_identifier （string）：服务器或服务器组UUID
start_revision （string）：开始提交哈希
end_revision （string）：结束提交哈希
branch （字符串，可选）：要从中部署的分支
mode （字符串，可选）：“队列”或“预览”
copy_config_files （布尔值，可选）：复制配置文件
run_build_commands （boolean，可选）：运行构建命令
use_build_cache （布尔值，可选）：使用构建缓存
use_latest （string，可选）：使用最新部署的commit作为开始

`list_ssh_keys`

列出帐户的所有SSH公钥。

退货：包含公钥、指纹和密钥类型的SSH密钥数组。从不返回私钥。

`create_ssh_key`

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

参数:

title （string）：SSH密钥的标题
key_type （字符串，可选）：密钥类型--ED25519（默认）或RSA

`list_global_environment_variables`

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

退货：具有名称、掩码值和设置的环境变量数组。

`create_global_environment_variable`

创建一个可在所有项目中使用的新全局环境变量。

参数:

name （string）：变量名称
value （string）：变量值
locked （boolean，可选）：锁定变量以防止更改
build_pipeline （boolean，可选）：在构建管道中可用

`update_global_environment_variable`

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

参数:

id （string）：环境变量标识符
name （字符串，可选）：变量名称
value （字符串，可选）：变量值
locked （布尔值，可选）：锁定状态
build_pipeline （布尔值，可选）：构建管道可用性

`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 （字符串，可选）：配置文件的描述
build （boolean，可选）：与构建管道一起使用

`update_global_config_file`

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

参数:

id （string）：配置文件标识符（UUID）
path （字符串，可选）：文件路径
body （字符串，可选）：文件内容
description （字符串，可选）：描述
build （布尔值，可选）：构建管道标志

`delete_global_config_file`

删除全局配置文件模板。这一行动是不可逆转的。

参数:

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

🚀 快速开始

使用Claude代码轻松安装

安装Claude Code的最快方法：

claude mcp add --transport stdio deployhq --env DEPLOYHQ_EMAIL=your-email@example.com --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server

替换 your-email@example.com, your-api-key，以及 your-account 使用您的实际DeployHQ凭据。

手动配置（适用于Claude桌面和Claude代码）

相同的配置适用于两个客户端。复制自 docs/claude-config.json 并添加您的凭据。

对于Claude Desktop：

编辑您的配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

然后重新启动Claude Desktop。

克劳德代码：

添加到您的 .claude.json 在项目目录中的文件，然后退出并重新启动Claude会话（键入 exit 或Ctrl+D，然后运行 claude).

配置：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "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创建新部署”
“显示最新部署的部署日志”
“列出我的全局环境变量”
“为数据库.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_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 环境变量：

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

例子：

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

🐛 故障排除

服务器无法启动

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

解决方案:

检查是否设置了所有必需的环境变量
验证Node.js版本是否为18或更高： node --version
检查克劳德桌面/代码中的日志以查看错误消息
尝试设置 LOG_LEVEL=DEBUG 详情请见

身份验证错误

问题：“身份验证失败”或401/403错误

解决方案:

验证您的电子邮件和API密钥是否正确
检查您的API密钥是否尚未过期
确保您的帐户已启用API访问
尝试使用相同的凭据登录DeployHQ web界面

未找到项目

问题：“找不到项目”或404错误

解决方案:

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

部署创建被阻止

问题：尝试创建部署时出现“服务器正在只读模式下运行”错误

解决方案:

默认情况下，只读模式被禁用，但您可能已经启用了它
要禁用只读模式，请设置 DEPLOYHQ_READ_ONLY=false 在环境变量中
或者使用 --read-only=false CLI标志
看安全只读模式的详细说明部分

部署失败

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

解决方案:

使用 get_deployment_log 查看详细的错误日志
使用验证服务器UUID是否正确 list_servers
检查存储库中是否存在开始和结束修订
确保服务器配置了正确的部署密钥

连接超时

问题：“请求超时”错误

解决方案:

检查你的网络连接
验证DeployHQ API是否可访问： curl https://YOUR_ACCOUNT.deployhq.com
大型部署列表可能需要时间-使用分页
如果DeployHQ遇到问题，请稍后重试

日志未显示

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

解决方案:

日志会转到stderr，而不是stdout（用于stdio传输）
检查克劳德桌面/代码日志位置：

- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%\Claude\logs\

集 LOG_LEVEL=DEBUG 详细输出
对于托管模式，请检查Digital Ocean日志

获取DeployHQ凭据

用户名：您的可部署登录电子邮件
密码：您的DeployHQ密码
账户：您的DeployHQ帐户名（在URL中可见： https://ACCOUNT.deployhq.com)

🏗️ 建筑

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

克劳德桌面/代码：通过生成服务器的MCP客户端 npx
MCP 服务器：从环境变量读取凭据，通过stdio进行通信
部署总部API：带有HTTP基本身份验证的REST API

📦 先决条件

Node.js 18+ （推荐节点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="your-email@example.com" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js

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

6.使用克劳德代码进行测试

配置您的本地 .claude.json 要使用内置版本，请执行以下操作：

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "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个测试
涵盖工具、api客户端和mcp服务器模块
使用模拟fetch进行隔离单元测试

🔒 安全

只读模式（可选）

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

对于需要额外保护以防止意外部署的用户，服务器包括 可选只读模式 可以启用该功能来阻止部署创建。

默认行为（无需配置）：

✅ 部署是 默认情况下允许
✅ 所有操作都有效：列出、获取和创建部署
✅ 开箱即用的完整功能

当您可能想启用只读模式时：

您希望通过AI获得额外的保护，防止意外部署
您正在连接到生产环境，并需要额外的安全层
您只需要读取权限即可监视部署
您仍在测试集成，希望保持谨慎

重要提示： 只读模式为 完全可选。服务器在没有它的情况下完全正常工作。

如何启用只读模式：

通过环境变量：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "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": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

配置优先级：

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

附加安全说明

部署日志可能包含秘密：部署日志可以包括环境变量、API密钥和其他敏感信息。使用检索日志的工具时要小心，特别是使用第三方人工智能服务时。

使用Least-Privilege API密钥：使用MCP访问所需的最低权限创建专用API密钥。为只读和读写操作考虑单独的键。

审核MCP活动：监控MCP的使用情况，特别是在生产环境中。定期查看日志，查看是否有意外行为。

环境变量：凭据从不存储，只通过环境变量传递

超文本传输安全协议：使用npx时，凭据保持在计算机本地

无遥测：除了直接发送到DeployHQ API之外，不会将任何数据发送到任何位置

______________________________________________________________________

🌐 可选：托管部署

服务器也可以部署为具有SSE/HTTP传输的托管服务。这对于web集成或共享团队访问非常有用。

🚀 部署到数字海洋

选项1：使用仪表板

准备您的存储库:

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

创建新应用程序:

- 首选数字海洋应用 - 点击“创建应用” - 选择您的GitHub存储库 - 选择分支（主）

配置应用程序:

- Digital Ocean将自动检测Dockerfile - 或者使用 .do/app.yaml 配置

设置环境变量:

- 转到应用程序设置→ 环境变量 - 添加以下内容 加密的 变量： - DEPLOYHQ_EMAIL - DEPLOYHQ_API_KEY - DEPLOYHQ_ACCOUNT - 将这些添加为常规变量： - NODE_ENV=production - PORT=8080 - LOG_LEVEL=info

部署:

- 点击“下一步”和“创建资源” - 等待部署完成

配置自定义域 （可选）：

- 转到“设置”→ 领域 - 添加 mcp.deployhq.com - 按照指示更新DNS记录

选项2：使用doctl CLI

安装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

验证:

   doctl auth init

更新 .do/app.yaml:

- 编辑 github.repo 存储库中的字段 - 必要时审查和调整实例大小

创建应用程序:

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

设置环境机密:

   # Get your app ID
   doctl apps list

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

查看日志:

   doctl apps logs APP_ID --follow

🔒 托管安全

从不提交凭据：使用 .env 地方发展（不包括 .gitignore)
使用数字海洋秘密：将凭据存储为加密的环境变量
仅限HTTPS：Digital Ocean提供自动HTTPS
最低权限：使用具有最低所需权限的专用DeployHQ用户

📊 托管监控

健康检查

托管服务器包括一个健康检查端点，位于 /health:

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

日志

在Digital Ocean中查看日志：

仪表板：转到您的应用程序→ 运行时日志
CLI： doctl apps logs --follow

警报

Digital Ocean将提醒您：

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

🧪 测试托管服务器

测试SSE端点：

curl -N http://localhost:8080/sse \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -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: your-email@example.com" \
  -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

🤝 贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

对于维护人员

看发布.md 有关创建版本和发布到npm的说明。

隐私政策

除了与DeployHQ API通信所需的数据外，此MCP服务器不会收集、存储或传输任何用户数据。凭据通过环境变量传递，从不记录或持久化。

有关DeployHQ的完整隐私政策，请参阅：https://www.deployhq.com/privacy

Deployhq MCP Server

快速接入

详细介绍

部署HQ MCP服务器

🚀 特性

📋 可用工具

list_projects

get_project

list_servers

list_deployments

get_deployment

get_deployment_log

create_deployment

list_ssh_keys

create_ssh_key

list_global_environment_variables

create_global_environment_variable

update_global_environment_variable

delete_global_environment_variable

list_global_config_files

get_global_config_file

create_global_config_file

update_global_config_file

delete_global_config_file

🚀 快速开始

使用Claude代码轻松安装

手动配置（适用于Claude桌面和Claude代码）

开始使用

💡 常见用法示例

检查部署状态

调试部署失败

部署最新更改

完整工作流示例

🔧 配置选项

环境变量

必需

可选的

日志级别

🐛 故障排除

服务器无法启动

身份验证错误

未找到项目

部署创建被阻止

部署失败

连接超时

日志未显示

获取DeployHQ凭据

🏗️ 建筑

📦 先决条件

🔧 本地开发

1.克隆存储库

2.安装依赖项

3.运行测试

4.建设项目

5.本地测试stdio传输

6.使用克劳德代码进行测试

🧪 测试

🔒 安全

只读模式（可选）

附加安全说明

🌐 可选：托管部署

🚀 部署到数字海洋

选项1：使用仪表板

选项2：使用doctl CLI

🔒 托管安全

📊 托管监控

健康检查

日志

警报

🧪 测试托管服务器

📚 项目结构

🤝 贡献

对于维护人员

隐私政策

📄 许可证

🆘 支持

🔗 相关链接

目录标签

接入字段

权限和风险

`list_projects`

`get_project`

`list_servers`

`list_deployments`

`get_deployment`

`get_deployment_log`

`create_deployment`

`list_ssh_keys`

`create_ssh_key`

`list_global_environment_variables`

`create_global_environment_variable`

`update_global_environment_variable`

`delete_global_environment_variable`

`list_global_config_files`

`get_global_config_file`

`create_global_config_file`

`update_global_config_file`

`delete_global_config_file`