STARWARCLOUD STARWAR.AI
返回市场
高性能MCP服务器

高性能MCP服务器

作者：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格式）

安装

  1. 克隆仓库：

    git clone https://github.com/NoASLR/htb-mcp-server.git
cd htb-mcp-server

  2. 构建二进制文件：

    go build -o htb-mcp-server main.go

  3. 获取您的HTB API令牌：

配置

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

必需

  • 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/                     # 文档

添加新工具

  1. 创建一个新的工具结构体，实现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) {
    // 实现
}

  2. 在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中断

故障排除

常见问题

  1. “HTB令牌无效或已过期”

    • 验证您的令牌是否正确且未过期
    • 确保令牌具有正确的JWT格式（由点分隔的三个部分）
    • 检查HTB个人设置中的令牌权限

  2. “连接被拒绝”

    • 验证网络连接到labs.hackthebox.com
    • 检查公司防火墙是否阻止了HTB API访问

  3. “超出速率限制”

    • 减少请求频率
    • 如有必要，增加RATE_LIMIT_PER_MINUTE

调试模式

启用调试日志：

export LOG_LEVEL=DEBUG
./htb-mcp-server

健康检查

测试服务器连通性：

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

贡献

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

许可证

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

致谢

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

发展路线图

第二阶段功能

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

长期目标

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

支持

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