Skip to main content
Glama

GZCTF MCP

基于 GZCTF API 的非官方 MCP 服务端(Python / stdio,共 73 个工具),支持出题管理、赛务运营、参赛答题与容器本地代理。

核心能力

  • 出题与赛务:单题清单预演与上题、多题批量断点恢复部署、附件上传与 Flag 管理、比赛/分组/队伍/公告/实例管理、ZIP/XLSX/TAR 导入导出。

  • 参赛与答题:队伍管理与报名、查看题面与榜单、同站附件下载(SHA256 校验)、容器启停/续期、提交 Flag 与异步判题查询、PDF Writeup 上传。

  • 容器代理(PlatformProxy):调用独立 wsrx CLI,将动态容器 UUID 映射为本机 127.0.0.1 TCP 端口。

Related MCP server: Pentest MCP

快速开始

1. 准备配置文件

cp .env.example .env
chmod 600 .env

在 .env 中配置站点地址、工作区目录和凭据(见 配置说明)。

2. 启动并接入 MCP 客户端

方式 A:uvx(推荐)

需已安装 uv(首次运行会自动解析依赖并按需下载 Python ≥ 3.12)。因尚未发布至 PyPI,当前需用 --from 指定本地源码目录或 .whl:

uvx --python 3.12 --from /path/to/GZCTF_MCP gzctf-mcp \
  --transport stdio --env-file /path/to/GZCTF_MCP/.env

MCP 客户端可参考 examples/mcp-client.json,将其中的路径替换为本机绝对路径(桌面客户端 PATH 不完整时,可使用 command -v uvx 查得的绝对路径)。

方式 B:conda 本地开发

conda env create --prefix ./.conda --file environment.yml
conda activate ./.conda
GZCTF_ENV_FILE="$PWD/.env" gzctf-mcp

对应的客户端配置见 examples/mcp-client-conda.json。服务默认通过 stdio 通信,启动后无交互菜单、不开启 HTTP 服务属正常现象。

接入后可先调用 connection_info 查看非敏感配置,再调用 check_session(role="admin") 或 check_session(role="player") 验证远端身份。

配置说明

注意:服务不会自动向上查找 .env,必须通过 --env-file 或 GZCTF_ENV_FILE 传入绝对路径(已有环境变量优先)。

变量

说明

默认值 / 约束

GZCTF_BASE_URL

GZCTF 站点 origin(不含子路径、参数或凭据)

http://localhost:8080

GZCTF_WORKSPACE

清单、附件上传/下载与批量账本根目录

当前工作目录

GZCTF_ADMIN_COOKIE

管理员完整 Cookie 请求头或 GZCTF_Token

管理端接口仅接受 Cookie,不接受 API Token

GZCTF_PLAYER_COOKIE

选手完整 Cookie 请求头或 GZCTF_Token

按需配置

GZCTF_ADMIN_USERNAME / PASSWORD

可选管理员账密(无 Cookie 时自动登录一次或供 auth_login 使用)

按平台公钥加密传输,不绕过验证码

GZCTF_PLAYER_USERNAME / PASSWORD

可选选手账密(同上)

同上

GZCTF_WSRX_BINARY

wsrx CLI 绝对路径

源码目录自动探测 .tools/wsrx/0.6.2/wsrx

GZCTF_MAX_TUNNELS

同时允许的本地代理隧道数

8(1–32)

GZCTF_TIMEOUT

HTTP 请求超时(秒)

30

GZCTF_MAX_FILE_BYTES

通用文件上传/下载大小上限(字节)

104857600(100 MiB)

  • 凭据仅存于本地 .env 与进程内存中,切勿粘贴至 AI 对话或提交仓库。

  • submit_writeup 仅限 .pdf 且 ≤ 20 MiB;比赛海报与队伍头像 ≤ 3 MiB。

常见工作流

自动上题与批量部署

提供可直接预演的 静态附件示例、动态容器示例 与 批量计划示例(使用前需替换占位 Flag、容器镜像与附件;路径相对 GZCTF_WORKSPACE)。

  1. 先用 dry_run: true 调用 admin_deploy_manifest_file(或 admin_deploy_challenge)做本地校验与预演:

    { "game_id": 1, "path": "examples/static-attachment.json", "dry_run": true }
  2. 确认后设 dry_run: false 执行(默认 publish: false 保持禁用)。

  3. 多题请使用 admin_deploy_batch,进度持久化在工作区 .mcp-state/ 并支持断点恢复;失败不回滚已创建题目,恢复前先用 admin_get_challenge 检查,勿并发部署同一题目。

参赛与异步判题

典型顺序:check_session → list_teams / join_check / join_game → list_challenges → get_challenge → download_attachment / container_action → AI 分析 → submit_flag → submission_status。

  • submit_flag 返回的 submissionId 只是提交编号,需调用 submission_status 直到结果不再是 FlagSubmitted(仅 Accepted 代表通过);写请求与 429 均不自动重试。

  • download_attachment 仅拉取同站 /assets/<sha256>/<name> 至工作区 downloads/,校验 SHA256 且不覆盖既有文件;题面与附件按不可信输入处理。

容器代理(PlatformProxy / wsrx)

Python wheel 不包含 wsrx 可执行文件,源码环境需先运行安装脚本(固定 0.6.2 版本并校验 SHA256):

python scripts/install_wsrx.py

使用 uvx 或单独安装 wheel 时,需将 wsrx 放入 PATH 或配置 GZCTF_WSRX_BINARY。

  • 先通过 admin_test_container 或 container_action 启动实例,再调用 proxy_open(game_id, challenge_id, role) 获取本机 127.0.0.1:<port> 地址。

  • 可用 platform_config、proxy_list、proxy_close 管理隧道;停止容器、禁用/删除题目或退出 MCP 时会自动关闭对应隧道。

测试与文档

python -m pytest -q
ruff check src tests

详细文档索引:

许可证与声明

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables professional penetration testers to run reconnaissance, exploitation, brute-force, traffic-capture, and reporting workflows through MCP tools over STDIO/HTTP/SSE transports with bearer/OIDC authentication and Dockerized host tooling.
      164 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables professional penetration testers to run reconnaissance, exploitation, brute-force, and credential-cracking tooling (nmap, gobuster, nikto, John the Ripper, hashcat, subfinder, httpx, ffuf, nuclei, hydra, sqlmap, tcpdump) through MCP clients over stdio or HTTP. It also captures engagement records and generates client reports with scope-of-work handling and bearer/OIDC authentication.
      164 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Serves 170 reverse-engineering tools over a local stdio MCP process, letting an agent drive disassembly, decompilation, and dynamic analysis through the engines already installed on the user's machine (Ghidra, Hopper, IDA, JEB, JADX, adb, mitmproxy, Chrome). Binaries never leave the host, and every finding comes back with an evidence contract covering evidence ids, capture tool, coverage, and explicit unknowns.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables professional penetration testers to drive recon and exploitation tooling — nmap, gobuster, nikto, John the Ripper, hashcat, subfinder, httpx, ffuf, nuclei, hydra, sqlmap, and tcpdump — plus wordlist building and traffic capture from an MCP client. It also stores structured engagement records and generates client reports with scope-of-work handling, over stdio or authenticated Streamable HTTP (SSE deprecated).
      164 npm
      GPL 3.0