CTFd

CTFd MCP Server

A Model Context Protocol (MCP) server for interacting with any CTFd v3 instance. It lets AI tools (Claude Desktop, Cursor, custom agents, ...) authenticate, list and inspect challenges, submit flags, and query instance state through a stable, type-safe interface.

The project ships two interfaces built on the same client library:

• MCP tools (primary) — ctfd_mcp_server.py, used over stdio or sse.
• REST API (optional) — server/main.py, a FastAPI mirror for scripting, debugging, and Docker deployments.

                 ┌──────────────────────────────────────────────┐

AI agent / MCP │ FastMCP (MCP tools) │ client ────────►│ set_token · login · challenges · submit_flag │ └──────────────────┬───────────────────────────┘ │ shared client ┌──────────────────▼───────────────────────────┐ curl / scripts ─►│ FastAPI REST (/api/v1/...) (optional) │ └──────────────────┬───────────────────────────┘ │ ┌──────────────────▼───────────────────────────┐ │ server.ctfd_client.CTFdClient │ │ └─ gateway.py (HTTP, auth, timeouts) │ └──────────────────┬───────────────────────────┘ │ HTTPS / HTTP ┌─────▼─────┐ │ CTFd │ └───────────┘

Credentials (token / cookie / password) live in memory only and are never echoed in tool output, written to server_state.json, or logged.

---

Features

• Multiple authentication modes — API token, session cookie, or username/password form login (with CSRF handling).
• Rich challenge queries — paginated listing with category, search (name), and solved/unsolved filters, plus per-challenge detail retrieval.
• Safe flag submission — requires an explicit confirm=True, returns clear success/failure, and surfaces rate-limit errors. Flags are never logged.
• Instance introspection — public instance info, health check, and an authentication-status tool that reveal no secrets.
• Consistent structured errors — AuthenticationError, CTFdAPIError, ChallengeNotFoundError, SubmissionError, ValidationError, ConfigurationError.
• Pagination by default — one page of challenges per call; no accidental full-dump downloads.
• Hardened HTTP — configurable timeouts, one safe retry for idempotent GETs, no retries for POSTs (no duplicate submissions), strict JSON/content parsing.
• REST + MCP from one codebase — identical behaviour on both interfaces.
• No hardcoded instance — BASE_URL is validated and configurable at startup and at runtime.

---

Installation

Requires Python 3.10+.

The fastest way is to install from [PyPI](https://pypi.org/project/ctfd-mcp-server/):

pip install ctfd-mcp-server

MCP stdio server with env config:

CTFD_BASE_URL=https://ctf.example.com CTFD_ADMIN_TOKEN=ctfd_... ctfd-mcp

optional REST interface:

ctfd-rest

For MCP clients, point your config at the packaged entry point:

{

"mcpServers": { "ctfd-mcp": { "command": "ctfd-mcp", "env": { "CTFD_BASE_URL": "https://demo.ctfd.io", "CTFD_ADMIN_TOKEN": "ctfd_..." } } } }

Or run from source:

git clone https://github.com/MrJamescot/ctfd-mcp-server.git

cd ctfd-mcp-server python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt

cp .env.example .env # then edit .env

Configure

CTFD_BASE_URL may include a path prefix (e.g. https://host/ctfd); the client

appends /api/v1 automatically.

---

Running the MCP Server

Most MCP clients launch the server themselves via a command/args config. For that, your client config should reference `ctfd_mcp_server.py`:

// e.g. Claude Desktop / mcp.json

{ "mcpServers": { "ctfd-mcp": { "command": "python", "args": ["/path/to/ctfd-mcp-server/ctfd_mcp_server.py"], "env": { "CTFD_BASE_URL": "https://demo.ctfd.io", "CTFD_ADMIN_TOKEN": "ctfd_..." } } } }

Manual launch:

# stdio (default) — used by MCP clients

python ctfd_mcp_server.py

SSE — expose over HTTP for remote/Docker use

CTFD_MCP_TRANSPORT=sse python ctfd_mcp_server.py # http://127.0.0.1:8000/sse

MCP tools

With token auth, requests are sent with Content-Type: application/json

(CTFd only honours Authorization: Token ... on JSON requests). With

cookie/credentials auth, state-changing requests echo the session CSRF nonce

as the CSRF-Token header, which is re-fetched from the site after login.

Tools return JSON text. Errors are structured, e.g.:

{ "error": { "type": "ChallengeNotFoundError", "message": "Challenge '99' not found (or not visible)." } }

---

Running the REST API (optional)

python scripts/run_local.sh           # reads .env, default http://127.0.0.1:8000

or

uvicorn server.main:app --host 0.0.0.0 --port 8000

Endpoints (all under /api/v1):

The optional REST API can be protected with an extra bearer token: set

CTFD_API_TOKEN, and requests to /api/v1/* will require

Authorization: Bearer . The server binds to loopback by default

(MCP_HOST=127.0.0.1).

---

Docker

A ready-made image is published on [Docker Hub](https://hub.docker.com/r/jamescot/ctfd-mcp-server):

docker run --rm -p 8000:8000 \

-e CTFD_BASE_URL=https://ctf.example.com \ -e CTFD_ADMIN_TOKEN=ctfd_... \ jamescot/ctfd-mcp-server

Or build locally (REST mode):

docker build -t ctfd-mcp .

docker run --rm -p 8000:8000 \ -e CTFD_BASE_URL=https://ctf.example.com \ -e CTFD_ADMIN_TOKEN=ctfd_... \ ctfd-mcp

docker compose up --build also works (REST API on `htt