HackTheBox MCP服务器
一种模型上下文协议（MCP）服务器，为AI助手提供对HackTheBox平台功能的编程访问。
特性
HTB MCP服务器提供了12个与HackTheBox平台交互的综合工具：
挑战管理
list_challenges-通过过滤获取分页的挑战列表start_challenge-初始化挑战环境submit_challenge_flag-提交挑战验证标志
机器管理
list_machines-获取具有状态信息的活动/退役机器start_machine-启动机器并获取连接详细信息get_machine_ip-检索活动计算机的IP地址submit_user_flag-提交机器的用户标志submit_root_flag-提交机器的根标志
用户管理
get_user_profile-检索用户配置文件和统计信息get_user_progress-获取完成状态和成就
搜索和实用程序
search_content-跨挑战/机器/用户的高级搜索get_server_status-健康检查和服务器信息
先决条件
- 转到1.21或更高版本
- 具有API访问权限的有效HackTheBox帐户
- HTB API令牌（JWT格式）
安装
- 克隆存储库：
git clone https://github.com/NoASLR/htb-mcp-server.git
cd htb-mcp-server- 构建二进制文件：
go build -o htb-mcp-server main.go- 获取您的HTB API令牌：
- 首选 HackTheBox配置文件设置 - 生成应用令牌 - 复制JWT令牌（格式： xxx.yyy.zzz)
配置
服务器是通过环境变量配置的：
必需
HTB_TOKEN-您的HackTheBox API代币（JWT格式）
可选的
SERVER_PORT-服务器端口（默认值：3000）LOG_LEVEL-日志记录级别：调试、信息、警告、错误（默认值：信息）RATE_LIMIT_PER_MINUTE-API速率限制（默认值：100）CACHE_TTL_SECONDS-响应缓存TTL（默认值：300）REQUEST_TIMEOUT_SECONDS-HTTP请求超时（默认值：30）
用法
单独模式
export HTB_TOKEN="your.jwt.token.here"
./htb-mcp-serverDocker模式
docker build -t htb-mcp-server .
docker run -e HTB_TOKEN="your.jwt.token.here" htb-mcp-serverMCP客户端集成
添加到您的MCP客户端配置中（例如，Claude Desktop）：
{
"mcpServers": {
"htb": {
"command": "/path/to/htb-mcp-server",
"env": {
"HTB_TOKEN": "your.jwt.token.here"
}
}
}
}示例用法
连接后，您可以通过AI助手使用这些工具：
# List active challenges
"Can you show me the available Web challenges on HackTheBox?"
# Start a machine
"Please start machine ID 123 and get its IP address"
# Submit a flag
"Submit the user flag 'HTB{example_flag}' for machine 123"
# Search for content
"Search for machines related to 'Active Directory'"
# Check server status
"What's the current status of the HTB MCP server?"API终点
服务器通过stdio传输实现MCP协议。所有通信均遵循JSON-RPC 2.0规范。
核心MCP方法
initialize-初始化MCP会话tools/list-列出可用工具tools/call-执行特定工具
HTB API集成
服务器与HackTheBox API v4:
- 基本URL:
https://labs.hackthebox.com/api/v4 - 身份验证：承载令牌（JWT）
- 速率限制：遵守HTB API限制
发展
项目结构
htb-mcp-server/
├── main.go # Entry point
├── pkg/
│ ├── config/ # Configuration management
│ ├── htb/ # HTB API client
│ └── mcp/ # MCP protocol implementation
├── internal/
│ ├── server/ # MCP server core
│ └── tools/ # Tool implementations
├── tests/ # Test files
└── docs/ # Documentation添加新工具
- 创建一个新的工具结构体，实现
Tool接口：
type MyTool struct {
client *htb.Client
}
func (t *MyTool) Name() string { return "my_tool" }
func (t *MyTool) Description() string { return "Description" }
func (t *MyTool) Schema() mcp.ToolSchema { /* schema */ }
func (t *MyTool) Execute(ctx context.Context, args map[string]interface{}) (*mcp.CallToolResponse, error) {
// Implementation
}- 在中注册该工具
registry.go:
r.RegisterTool(NewMyTool(r.htbClient))测试
# Run unit tests
go test ./...
# Run with coverage
go test -cover ./...
# Run integration tests (requires HTB_TOKEN)
HTB_TOKEN="your.token" go test -tags=integration ./...安全考虑
- 令牌安全：永远不要将HTB令牌提交给版本控制
- 速率限制：服务器实现速率限制以防止API滥用
- 输入验证：在API调用之前验证所有用户输入
- 错误处理：敏感信息不会在错误消息中暴露
演出
- 响应时间：95%的请求\<500ms
- 缓存：智能缓存减少了API调用
- 并发：支持多个并发工具执行
- 断路器：防止HTB API中断
故障排除
常见问题
- “HTB令牌似乎无效或已过期”
- 验证您的令牌是否正确且未过期 - 确保令牌具有正确的JWT格式（由点分隔的3个部分） - 检查HTB配置文件设置中的令牌权限
- “连接被拒绝”
- 验证labs.hacktebox.com的网络连接 - 检查公司防火墙是否阻止HTB API访问
- “超出费率限制”
- 降低请求频率 - 增加 RATE_LIMIT_PER_MINUTE 如有需要
调试模式
启用调试日志记录：
export LOG_LEVEL=DEBUG
./htb-mcp-server健康检查
测试服务器连接：
curl -X POST http://localhost:3000/health贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- 提供API的HackTheBox团队
- 规范的模型上下文协议社区
- 去社区寻找优秀的工具和库
路线图
第二阶段特征
- 实时机器状态通知
- 高级分析和报告
- 团队协作功能
- 自定义挑战创建工具
长期目标
- 移动应用支持
- 与其他安全平台集成
- 先进的自动化能力
- 基于机器学习的推荐
支持
- 问题:
- 文档: 维基
______________________________________________________________________
内置于❤️ 网络安全社区