CTFD

You can use this MCP server to interact with a CTFd instance from a client, see available challenges, read details, manage dynamic containers, and submit flags. It unifies actions across the CTFd environment so you can drive challenge workflows from a single interface.

How to use

You connect a client to the MCP server to list visible challenges, view challenge details, start and stop dynamic containers, and submit flags. The server exposes a set of functions that you call from your MCP client, such as listing challenges, retrieving challenge details, submitting a flag, and controlling containers. All attachments associated with challenges are provided as absolute URLs, so your client can fetch them directly.

Key functions you can use include:

• list_challenges(category?, only_unsolved?) — lists visible challenges with optional category and unsolved filters
• challenge_details(challenge_id) — fetches the description, metadata, attachments, and solved status
• submit_flag(challenge_id, flag) — submits a solution and returns the result
• start_container(challenge_id) — starts the corresponding dynamic instance (Docker, Owl, or Kubernetes)
• stop_container(container_id?, challenge_id?) — stops a running instance; the command adapts to the container type

If a challenge provides attachment files, those URLs are returned in the response so your client can download them directly.

How to install

Prerequisites you need before running the MCP server are listed below. Install them on your system, then start the MCP server so your client can connect.

Prerequisites

• Python 3.13 or newer (the server is managed by the uv helper)
• uvx command runner (for executing MCP commands)

Install and run the MCP server using one of the following pathways. Choose the recommended approach or the local setup that fits your environment.

uvx ctfd-mcp --help
# or, from a local checkout
uvx --from . ctfd-mcp --help

Additional configuration and usage notes

Configure environment variables to connect to your CTFd instance. You can provide authentication information in one of several ways. The secure approach is to use a session token or a user token, or you can use a browser session cookie if tokens are disabled. You can place these values in a .env file or export them in your shell.

CTFD_URL=https://ctfd.example.com/
CTFD_USERNAME=your_username
CTFD_PASSWORD=your_password
# or, alternatively, 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

Examples of MCP server configuration

The MCP server can be run using a local stdio configuration, or you can point to a remote MCP endpoint. The following examples show how to configure the local stdio approach.

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

Security considerations

If you are redirected to a login page (302) when using a token, switch to a browser session cookie by setting CTFD_SESSION from the session cookie after logging in. The client’s authentication priority is username/password first, then token, then session cookie; lower-priority credentials are ignored when a higher-priority option is present.

Troubleshooting

Dynamic containers require the ctfd-whale dynamic_docker plugin on the target CTFd instance. If you do not have this plugin enabled, you may see 404 errors for container endpoints. Owl challenges use a different endpoint and often require a session cookie; set CTFD_CSRF_TOKEN if your setup requires it.

If you encounter rate limits, check for a Retry-After header and adjust retries accordingly. Other HTTP/API errors should surface as MCP errors with the CTFd message and status.

Developer notes

The MCP server supports a set of exposed tools that let you list challenges, view details, submit flags, and manage containers in a unified way. This is designed to streamline interactions with CTFd from a single client.

Available tools

list_challenges

List visible challenges with optional category and unsolved filters.

challenge_details

Fetch challenge description, HTML, metadata, attachments, and solved status.

submit_flag

Submit a solution for a challenge and receive status and feedback.

start_container

Unified start for dynamic containers: detects dynamic_docker, ctfd-owl, or k8s endpoints and initiates the instance.

stop_container

Unified stop for dynamic containers; stops by container_id or via challenge context where applicable.