Skip to main content
Glama
CTFd MCP Server

CTFd MCP Server

by umbra2728

CTFd MCP server (user scope)

GitHub Release License Python Issues

MCP server that lets a regular CTFd user list challenges, read details, start/stop dynamic docker instances, and submit flags.

Requirements

  • Python 3.13 (managed by uv).

  • Environment variables (choose one auth method):

  • CTFD_URL (e.g. https://ctfd.example.com)

  • CTFD_TOKEN (user token, not admin) or CTFD_SESSION (session cookie if tokens are disabled).

    • CTFD_CSRF_TOKEN (optional, only if the server/plugin requires CSRF for ctfd-owl).

You can store them in a .env file in the repo root:

CTFD_URL=https://ctfd.example.com/
CTFD_USERNAME=your_username
CTFD_PASSWORD=your_password
# or, if you prefer to use a token:
# CTFD_TOKEN=your_ctfd_api_token_here
# or, if tokens are disabled:
# CTFD_SESSION=your_session_token_here
# and, if the owl plugin enforces CSRF:
# CTFD_CSRF_TOKEN=your_csrf_token_here

Related MCP server: CTF MCP Server

Install

  • From PyPI (recommended): uvx ctfd-mcp --help

  • From source checkout (no install): uvx --from . ctfd-mcp --help

Run MCP server (stdio)

# installed from PyPI
uvx ctfd-mcp
# from local checkout
uvx --from . ctfd-mcp

Cursor and Claude MCP config example

{
  "mcpServers": {
    "ctfd-mcp": {
      "command": "uvx",
      "args": ["ctfd-mcp"],
      "env": {
        "CTFD_URL": "https://ctfd.example.com",
        "CTFD_TOKEN": "your_user_token"
      }
    }
  }
}

Codex MCP config example

[mcp_servers.ctfd-mcp]
command = "uvx"
args = ["ctfd-mcp"]

[mcp_servers.ctfd-mcp.env]
CTFD_URL = "https://ctfd.example.com"
CTFD_TOKEN = "your_user_token"

Exposed tools

  • list_challenges(category?, only_unsolved?) — list visible challenges, optional category/unsolved filter.

  • challenge_details(challenge_id) — description (HTML + description_text), metadata, attachment URLs, solved status.

  • submit_flag(challenge_id, flag) — attempt a flag; returns status/message.

  • start_container(challenge_id) — unified start; auto-detects dynamic_docker, ctfd-owl or k8s /api/v1/k8s.

  • stop_container(container_id?, challenge_id?) — unified stop; whale can be stopped with just container_id, owl/k8s need challenge_id.

Attachments are returned as absolute URLs in files; the client/host can fetch them directly.

MCP resources

  • resource://ctfd/challenges/{challenge_id} — markdown snapshot of a challenge (metadata, description, attachment URLs, connection info if present).

Error handling

  • Missing env/config -> clear MCP error.

  • 401/403 -> auth failed, check token or session cookie.

  • 404 -> not found (or dynamic container API missing).

  • 429 -> rate limited (Retry-After if present).

  • Other HTTP/API errors -> surfaced as MCP errors with CTFd message/status.

Notes and troubleshooting

  • Dynamic containers require the ctfd-whale (dynamic_docker) plugin on the target CTFd; otherwise /api/v1/containers returns 404.

  • Owl challenges (dynamic_check_docker) use a different endpoint: /plugins/ctfd-owl/container?challenge_id=<id>. They usually require a session cookie, and some setups require a CSRF token; set CTFD_CSRF_TOKEN if needed.

  • Some events expose Kubernetes-backed instances at /api/v1/k8s/{get,create,delete} with multipart form data; the client will try these when the challenge type includes k8s (or when a dynamic_docker endpoint is missing).

  • If the server redirects you to /login (302) when using a token, switch to a browser session cookie: set CTFD_SESSION from the session cookie after logging in.

  • The client now supports logging in with CTFD_USERNAME and CTFD_PASSWORD; these fields take precedence over stale tokens/sessions.

  • Auth priority: username/password first, then token, then session cookie. Lower-priority credentials are ignored when a higher-priority option is present.

Support / feedback

If something breaks or you have questions, reach out:

Testing

  • Run uv run pytest.

  • Timeouts are configurable via env: CTFD_TIMEOUT (total), CTFD_CONNECT_TIMEOUT, CTFD_READ_TIMEOUT (seconds). Defaults are 20s total / 10s connect / 15s read.

Development

  • Dev dependencies: uv sync --group dev

  • Lint/format: uv run ruff check . and uv run ruff format .

  • Tests: uv run pytest

  • Pre-commit: uv run pre-commit install (see CONTRIBUTING.md)

License

Apache-2.0. See LICENSE.

Available Tools

5 tools
challenge_detailsA

Get challenge details (description, files, meta) by ID.

Inputs: challenge_id (required).

list_challengesB

List visible challenges. Optional filter by category and unsolved only.

Inputs: category, only_unsolved.

start_containerB

Unified start: detects plugin (whale/ctfd-owl/k8s) and starts container.

Inputs: challenge_id (required).

stop_containerC

Unified stop: whale requires container_id; ctfd-owl/k8s require challenge_id.

Inputs: container_id, challenge_id.

submit_flagC

Submit a flag for a challenge ID.

Inputs: challenge_id (required), flag (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct action: starting/stopping containers, listing challenges, viewing details, and submitting flags. There is no overlap between the five tools.

    Naming Consistency4/5

    Tool names follow a consistent verb_noun pattern (start_container, list_challenges, challenge_details, submit_flag, stop_container). 'challenge_details' is a noun phrase rather than a verb_noun like 'get_challenge', but the pattern is still clear and predictable.

    Tool Count5/5

    Five tools is well-scoped for a CTFd server: it covers the core user-facing actions of browsing challenges, getting details, submitting flags, and managing challenge containers. Each tool earns its place.

    Completeness4/5

    The surface covers the main CTF participant workflow: list challenges, view details, start/stop containers, and submit flags. Minor gaps exist such as no tool for viewing container status or listing active containers, but agents can work around these with the provided tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Exposes common CTF and cybersecurity tools (crypto, forensics, malware analysis, steganography, reverse engineering, pwn, OSINT) so LLMs can help solve capture-the-flag challenges in a controlled lab environment.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to interact with the FlagForge REST API, allowing them to search solved CTF challenges, work on live event challenges, record evidence, submit flag candidates, and write markdown writeups.
      19
      ISC