高性能MCP服务器

Name: 高性能MCP服务器
Author: noaslr

作者：noaslr2 星标更新：2025-07-27

安装使用来源：spider==github.com

项目介绍

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 - 提交机器的root标志

用户管理

get_user_profile - 获取用户资料和统计数据
get_user_progress - 获取完成状态和成就

搜索与实用工具

search_content - 在挑战、机器和用户之间进行高级搜索
get_server_status - 健康检查和服务器信息

预备条件

Go 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个人设置页面
- 生成一个App Token
- 复制JWT令牌（格式：xxx.yyy.zzz）

配置

服务器通过环境变量进行配置：

必需

HTB_TOKEN - 您的HackTheBox API令牌（JWT格式）

可选

SERVER_PORT - 服务器端口（默认：3000）
LOG_LEVEL - 日志级别：DEBUG, INFO, WARN, ERROR（默认：INFO）
RATE_LIMIT_PER_MINUTE - API速率限制（默认：110）
CACHE_TTL_SECONDS - 响应缓存TTL（默认：300）
REQUEST_TIMEOUT_SECONDS - HTTP请求超时（默认：30）

使用方法

独立模式

export HTB_TOKEN="your.jwt.token.here"
./htb-mcp-server

Docker模式

docker build -t htb-mcp-server .
docker run -e HTB_TOKEN="your.jwt.token.here" htb-mcp-server

MCP客户端集成

在您的MCP客户端配置中添加（例如，Claude Desktop）：

{
  "mcpServers": {
    "htb": {
      "command": "/path/to/htb-mcp-server",
      "env": {
        "HTB_TOKEN": "your.jwt.token.here"
      }
    }
  }
}

示例用法

一旦连接，您可以通过您的AI助手使用这些工具：

# 列出活跃挑战
"你能给我展示一下HackTheBox上的可用Web挑战吗？"

# 启动一台机器
"请启动机器ID 123并获取其IP地址"

# 提交一个标志
"提交机器123的用户标志'HTB{example_flag}'"

# 搜索内容
"搜索与'Active Directory'相关的机器"

# 检查服务器状态
"HTB MCP服务器当前的状态是什么？"

API端点

该服务器通过标准I/O传输实现MCP协议。所有通信遵循JSON-RPC 2.0规范。

核心MCP方法

initialize - 初始化MCP会话
tools/list - 列出可用工具
tools/call - 执行特定工具

HTB API集成

服务器集成了HackTheBox API v4：

基础URL：https://labs.hackthebox.com/api/v4
认证：Bearer令牌（JWT）
速率限制：遵守HTB API限制

开发

项目结构

htb-mcp-server/
├── main.go                    # 入口点
├── pkg/
│   ├── config/               # 配置管理
│   ├── htb/                  # HTB API客户端
│   └── mcp/                  # MCP协议实现
├── internal/
│   ├── server/               # MCP服务器核心
│   └── tools/                # 工具实现
├── tests/                    # 测试文件
└── docs/                     # 文档

添加新工具

创建一个新的工具结构体，实现Tool接口：

type MyTool struct {
    client *htb.Client
}

func (t *MyTool) Name() string { return "my_tool" }
func (t *MyTool) Description() string { return "描述" }
func (t *MyTool) Schema() mcp.ToolSchema { /* schema */ }
func (t *MyTool) Execute(ctx context.Context, args map[string]interface{}) (*mcp.CallToolResponse, error) {
    // 实现
}

在registry.go中注册工具：
```
r.RegisterTool(NewMyTool(r.htbClient))
```

测试

# 运行单元测试
go test ./...

# 运行带覆盖率的测试
go test -cover ./...

# 运行集成测试（需要HTB_TOKEN）
HTB_TOKEN="your.token" go test -tags=integration ./...

安全注意事项

令牌安全：切勿将您的HTB令牌提交到版本控制
速率限制：服务器实现了速率限制以防止API滥用
输入验证：所有用户输入在API调用前都会被验证
错误处理：敏感信息不会暴露在错误消息中

性能

响应时间：95%的请求响应时间小于500毫秒
缓存：智能缓存减少了API调用
并发性：支持多个工具的同时执行
断路器：保护HTB API中断

故障排除

常见问题

“HTB令牌无效或已过期”
- 验证您的令牌是否正确且未过期
- 确保令牌具有正确的JWT格式（由点分隔的三个部分）
- 检查HTB个人设置中的令牌权限
“连接被拒绝”
- 验证网络连接到labs.hackthebox.com
- 检查公司防火墙是否阻止了HTB API访问
“超出速率限制”
- 减少请求频率
- 如有必要，增加RATE_LIMIT_PER_MINUTE

调试模式

启用调试日志：

export LOG_LEVEL=DEBUG
./htb-mcp-server

健康检查

测试服务器连通性：

curl -X POST http://localhost:3000/health

贡献

分叉仓库
创建一个特性分支
进行更改
为新功能添加测试
提交拉取请求

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件了解详细信息。

致谢

HackTheBox团队提供API
模型上下文协议社区提供规范
Go社区提供优秀的工具和库

发展路线图

第二阶段功能

实时机器状态通知
高级分析和报告
团队协作功能
自定义挑战创建工具

长期目标

移动应用支持
与其他安全平台的集成
高级自动化能力
基于机器学习的推荐

支持

问题：GitHub Issues
文档：Wiki

为网络安全社区打造，充满爱心