CTFd MCP Server

A lightweight and extensible Model Context Protocol (MCP) server for interacting with any CTFd instance. This project enables AI tools and automation to authenticate, retrieve challenges, and submit flags through MCP tools.

Overview

This project acts as a bridge between CTFd and AI-driven systems by providing a unified interface. It supports multiple authentication modes, dynamic base URL control, and direct MCP tool integration.

The server is validated using the official demo instance at https://demo.ctfd.io.

Features

• Dynamic BASE_URL configuration
• Token and cookie authentication
• Username/password login
• List challenges with optional filtering
• Submit flags programmatically
• Compatible with MCP-based AI tools (Claude, Codex, Amp, Gemini)
• Clean and extensible TypeScript codebase

Quickstart

Option 1: npx (no install)

npx ctfd-mcp-server

Option 2: Global install

pnpm install -g ctfd-mcp-server
ctfd-mcp-server

Option 3: From source

git clone https://github.com/tomek7667/ctfd-mcp-server.git
cd ctfd-mcp-server
pnpm install
pnpm run build
pnpm start

Tools

Tool	Description
set_base_url(url)	Set the base URL for the CTFd instance
set_token(token)	Set authentication token
set_cookie(cookie)	Set session cookie
login(username, password)	Login with credentials
challenges(category?)	List challenges, optionally filtered by category
challenge(identifier)	Get challenge details by name or ID
submit_flag(challenge_name?, challenge_id?, flag)	Submit a flag
scoreboard()	Get the CTFd scoreboard
progress()	Get current user's progress
health()	Check connection health

---

Client Setup

Claude Desktop

Claude Desktop supports MCP servers via a JSON configuration file.

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (recommended):

{
	"mcpServers": {
		"ctfd": {
			"command": "npx",
			"args": ["-y", "ctfd-mcp-server"],
			"env": {
				"BASE_URL": "https://demo.ctfd.io",
				"CTFD_TOKEN": "<your ctfd api token>"
			}
		}
	}
}

Using global install:

{
	"mcpServers": {
		"ctfd": {
			"command": "ctfd-mcp-server",
			"env": {
				"BASE_URL": "https://demo.ctfd.io",
				"CTFD_TOKEN": "<your ctfd api token>"
			}
		}
	}
}

Restart Claude Desktop after editing the config.

---

OpenAI Codex CLI

Codex CLI stores MCP configuration in ~/.codex/config.toml.

Using the CLI:

codex mcp add ctfd -- npx -y ctfd-mcp-server

Or edit ~/.codex/config.toml directly:

[mcp_servers.ctfd]
command = "npx"
args = ["-y", "ctfd-mcp-server"]

[mcp_servers.ctfd.env]
BASE_URL = "https://demo.ctfd.io"
CTFD_TOKEN = "<your ctfd api token>"

Use /mcp in the Codex TUI to verify the server is connected.

---

Amp

Amp supports MCP servers via the amp.mcpServers setting in VS Code settings.json.

Config file location (VS Code):

• macOS: ~/Library/Application Support/Code/User/settings.json
• Windows: %APPDATA%\Code\User\settings.json
• Linux: ~/.config/Code/User/settings.json

Using npx (recommended):

{
	"amp.mcpServers": {
		"ctfd": {
			"command": "npx",
			"args": ["-y", "ctfd-mcp-server"],
			"env": {
				"BASE_URL": "https://demo.ctfd.io",
				"CTFD_TOKEN": "<your ctfd api token>"
			}
		}
	}
}

Via CLI:

amp mcp add ctfd npx -y ctfd-mcp-server

---

Gemini CLI

Gemini CLI stores MCP configuration in ~/.gemini/settings.json.

Using npx (recommended):

{
	"mcpServers": {
		"ctfd": {
			"command": "npx",
			"args": ["-y", "ctfd-mcp-server"],
			"env": {
				"BASE_URL": "https://demo.ctfd.io",
				"CTFD_TOKEN": "<your ctfd api token>"
			}
		}
	}
}

Via CLI:

gemini mcp add ctfd npx -- -y ctfd-mcp-server

Use /mcp in Gemini CLI to verify server status.

---

Docker

docker build -t ctfd-mcp-server .
docker run -i ctfd-mcp-server

For clients that support Docker-based MCP servers:

{
	"mcpServers": {
		"ctfd": {
			"command": "docker",
			"args": ["run", "-i", "--rm", "ctfd-mcp-server"]
		}
	}
}

---

Compatibility

Feature	Supported
Transport	stdio
Node.js	>=18.0.0
Platforms	macOS, Linux, Windows

Tested Clients

Client	Status
Claude Desktop	✅ Verified
OpenAI Codex CLI	✅ Verified
Amp	✅ Verified
Gemini CLI	✅ Verified

---

Environment Variables

Variable	Description	Default
BASE_URL	CTFd instance base URL	https://demo.ctfd.io

---

Development

# Clone and install
git clone https://github.com/tomek7667/ctfd-mcp-server.git
cd ctfd-mcp-server
pnpm install

# Build
pnpm run build

# Run
pnpm start

# Watch mode (auto-rebuild)
pnpm run watch

---

Support

For support, email [email protected] or open an issue through the GitHub repository. Community contributions and improvements are always welcome.

License

MIT