ctfd-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ctfd-mcp show me the unsolved challenges, easiest first"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ctfd-mcp
A tiny, standalone MCP server for any CTFd-based CTF. Point your agent (opencode, Claude Code, Claude Desktop, Cursor, …) at it and it can browse and read challenges, download their files, submit flags, watch the scoreboard — and, when the CTF uses the ctfd-whale plugin, start/stop your per-team instances. Two env vars, no framework to learn, no repo to graft into, no hours of debugging.
Self-contained — the only dependencies are
mcpandhttpx.Works on any CTFd — token auth, team or user mode (auto-detected), pagination.
Robust — every tool returns clean JSON, even on errors (a closed CTF returns
{"error":"HTTP 403", ...}instead of crashing your session).ctfd-whale aware — dynamic instance tools auto-disable when the plugin isn't present.
Install
# Recommended — installs from THIS repo and puts `ctfd-mcp` on your PATH:
pipx install "git+https://github.com/sanjarbiy/ctfd-mcp"
# or with pip:
pip install "git+https://github.com/sanjarbiy/ctfd-mcp"
# --- or from a local clone ---
git clone https://github.com/sanjarbiy/ctfd-mcp && cd ctfd-mcp
python3 -m venv .venv && .venv/bin/pip install -e . # Windows: .venv\Scripts\pip install -e .⚠️ Install from the repo URL, not the bare name. An unrelated package called
ctfd-mcpexists on PyPI — a plainpip install ctfd-mcpwould fetch that, not this project. Also requiresmcp>=1.2,<2(FastMCP 1.x runs async tools reliably;mcp2.x is intentionally excluded) — the pin is handled for you when you install from the URL above.
Related MCP server: CyberEdu MCP Server
Configure
Get an Access Token in CTFd: Settings → Access Tokens → Generate (ctfd_...).
Then set two env vars (or drop a .env next to where you run it — see .env.example):
var | required | meaning |
| ✅ | e.g. |
| ✅ | your CTFd access token |
| download dir (default | |
| per-request seconds (default | |
|
| |
|
|
Add it to your agent
opencode (~/.config/opencode/opencode.jsonc → "mcp"):
"ctfd": {
"type": "local",
"command": ["ctfd-mcp"],
"environment": { "CTFD_URL": "https://YOUR-CTF", "CTFD_TOKEN": "ctfd_..." },
"enabled": true
}Claude Code:
claude mcp add ctfd -s user -e CTFD_URL=https://YOUR-CTF -e CTFD_TOKEN=ctfd_... -- ctfd-mcpClaude Desktop / Cursor (mcpServers):
"ctfd": { "command": "ctfd-mcp", "env": { "CTFD_URL": "https://YOUR-CTF", "CTFD_TOKEN": "ctfd_..." } }(If you didn't pip install, use the venv python: "command": "/path/ctfd-mcp/.venv/bin/python", "args": ["-m","ctfd_mcp"].)
Tools
tool | what it does |
| list challenges, easy-first (most solves) |
| full details: description, connection_info, files, hints, tags |
| download the challenge's CTFd-hosted files |
| submit a flag → |
| names you/your team already solved |
| list hints (optionally spend points to unlock) |
| live top-N standings |
| your team/user info (auto-detects CTFd mode) |
| GET any file off a challenge instance/service |
| [ctfd-whale] your live dynamic instances |
| [ctfd-whale] start an instance → host/URL |
| [ctfd-whale] destroy your instance |
challenge is an id or a name (exact match wins, else substring). Every tool returns JSON.
Typical flow
ctf_list unsolved=true # triage, easy-first
ctf_show "Baby RSA" # read it
ctf_download "Baby RSA" # get the files (or: whale_start + fetch_url for dynamic ones)
# ...you solve it...
ctf_submit "Baby RSA" "flag{...}" # submitTroubleshooting
{"error":"HTTP 403"}on challenge tools — the CTF hasn't started, has ended, or the token lacks access.ctf_mestill works (it confirms your token is valid).{"error":"HTTP 401"}— bad/expiredCTFD_TOKEN.ctfd-whale tools return
not available— this CTF has no ctfd-whale plugin; usectf_download(static files) instead.Self-signed lab CTFd — set
CTFD_VERIFY_TLS=0(trusted networks only; see the env table).Only
mcp>=1.2,<2is supported (async tools break undermcp2.x).
Security notes
This server is driven by an LLM whose context fills with untrusted challenge text (descriptions, hints, files). Keep that in mind:
fetch_urlis a fetch-any-URL tool. A crafted challenge could try to make the agent fetch an internal address (SSRF). It refuses non-http(s)schemes and always blocks cloud-metadata / link-local (169.254.x); private/loopback hosts are allowed by default (real CTF instances live there) — setCTFD_ALLOW_PRIVATE_FETCH=0to lock that down. Only the initial host is checked, not redirect targets.File downloads never carry your API token (they use a token-less client), so a malicious file URL can't exfiltrate
CTFD_TOKEN.Your token lives only in the process env / a local
.env(git-ignored) — never commit it.
License
MIT — see LICENSE.
Available Tools
12 toolsctf_downloadA
Download a challenge's CTFd-hosted files (id or name) into CTFD_FILES_DIR//. Returns dir + saved files + connection_info.
Inputs: challenge (required). Returns: result
ctf_hintsA
List hints for a challenge (id or name). unlock=True spends points to reveal content (default: just list titles/costs).
Inputs: challenge (required), unlock. Returns: result
ctf_listB
List challenges. unsolved=True hides solved; filter by category/name; easy-first (most solves). Returns id, name, category, value, solves, solved.
Inputs: name, limit, category, unsolved. Returns: result
ctf_meA
Your own team (team mode) or user (user mode) info: name, score, place. Auto-detects the CTFd mode.
Inputs: no named parameters. Returns: result
ctf_scoreboardB
Live scoreboard: top N teams/users by score.
Inputs: top. Returns: result
ctf_showA
Full details for one challenge (id or name): description, connection_info, files, hints, tags, value, solves.
Inputs: challenge (required). Returns: result
ctf_solvedA
List challenge names already solved by you / your team.
Inputs: no named parameters. Returns: result
ctf_submitA
Submit a flag for a challenge (id or name). Returns {status: correct/incorrect/already_solved/paused/ratelimited, message}.
Inputs: flag (required), challenge (required). Returns: result
fetch_urlA
GET any URL (e.g. a challenge instance file http://host/files/x.pcap) and save it to CTFD_FILES_DIR/_fetched/. Returns path, size and a short text preview. For services that serve files off-CTFd.
Inputs: url (required). Returns: result
whale_listA
[ctfd-whale] List your team's LIVE dynamic instances: challenge, category, access host, remaining seconds. Returns {error} if the CTF has no ctfd-whale plugin.
Inputs: no named parameters. Returns: result
whale_startB
[ctfd-whale] Start a dynamic instance for a challenge (id or name). Returns {host, access, remaining_s} or {slots_full, detail}.
Inputs: challenge (required). Returns: result
whale_stopA
[ctfd-whale] Stop/destroy the dynamic instance for a challenge you own (id or name).
Inputs: challenge (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target distinct resources/actions (list, show, download, submit, hints, scoreboard, me, whale instances). Minor overlap between ctf_solved and ctf_list (which can hide solved), and ctf_me vs ctf_scoreboard, but descriptions clarify boundaries well.
Clean ctf_-prefixed verb/noun pattern across the core eight tools, with whale_* grouping the plugin tools consistently. fetch_url deviates from the prefix scheme but is a single understandable outlier.
12 tools is well-scoped for a CTFd client, covering the full player workflow plus dynamic instances without redundancy. Each tool earns its place.
Strong lifecycle coverage: discover, inspect, download, submit, hints, scoreboard, personal info, and whale instance control. Missing team join/create and some auth management, but core competitive workflows are covered.
Maintenance
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
MCP Server for an Agent Task Marketplace
Find verified MCP servers and agents for a task, register yours, report outcomes. Earned scores.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceMCP server that provides tools for interacting with the Fluidattacks API-- FlicenseNot gradedqualityDmaintenanceOfficial MCP server for the CyberEdu CTF platform that automatically discovers and exposes all CyberEduClient methods as tools, enabling seamless interaction with the platform through MCP-compatible clients.8-
- AlicenseAqualityBmaintenanceA lightweight MCP server for interacting with CTFd instances, enabling AI tools to authenticate, retrieve challenges, and submit flags.1456 PyPI7MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that wraps common forensic command-line tools for CTF/forensics competitions into MCP tools, enabling automated analysis of disk images, memory dumps, network captures, SQLite databases, archives, and steganography.1MIT