mcp-ctftime

An MCP (Model Context Protocol) server that wraps the public CTFtime API, enabling AI assistants to query CTF events, teams, rankings, and results.

Quickstart

Option 1: npx (no install)

npx mcp-ctftime

Option 2: Global install

npm install -g mcp-ctftime
mcp-ctftime

Option 3: From source

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

Tools

Tool	Description
ctftime_events(limit?, start?, finish?)	List events in a UNIX timestamp window
ctftime_event(event_id)	Get event details by ID
ctftime_top_teams(year?, limit?)	Get top teams (current or specific year)
ctftime_top_by_country(country_code)	Get top teams by country (current year)
ctftime_team(team_id)	Get team details by ID
ctftime_results(year?)	Get event results for a year
ctftime_votes(year)	Get event votes for a year

---

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": {
		"ctftime": {
			"command": "npx",
			"args": ["-y", "mcp-ctftime"]
		}
	}
}

Using global install:

{
	"mcpServers": {
		"ctftime": {
			"command": "mcp-ctftime"
		}
	}
}

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 ctftime -- npx -y mcp-ctftime

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

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

Using global install:

[mcp_servers.ctftime]
command = "mcp-ctftime"

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 or via CLI.

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": {
		"ctftime": {
			"command": "npx",
			"args": ["-y", "mcp-ctftime"]
		}
	}
}

Using global install:

{
	"amp.mcpServers": {
		"ctftime": {
			"command": "mcp-ctftime"
		}
	}
}

Via CLI:

amp mcp add ctftime npx -y mcp-ctftime

---

Gemini CLI

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

Using npx (recommended):

{
	"mcpServers": {
		"ctftime": {
			"command": "npx",
			"args": ["-y", "mcp-ctftime"]
		}
	}
}

Using global install:

{
	"mcpServers": {
		"ctftime": {
			"command": "mcp-ctftime"
		}
	}
}

Via CLI:

gemini mcp add ctftime npx -- -y mcp-ctftime

Use /mcp in Gemini CLI to verify server status.

---

Docker

docker build -t mcp-ctftime .
docker run -i mcp-ctftime

For clients that support Docker-based MCP servers:

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

---

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

Currently, this server does not require any environment variables. The CTFtime API is public and does not require authentication.

---

Development

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

# Build
pnpm build

# Run
pnpm start

# Watch mode (auto-rebuild)
pnpm watch

---

API Reference

This server wraps the public CTFtime API: https://ctftime.org/api/

All timestamps use UNIX epoch seconds. Country codes use ISO 3166-1 alpha-2 format (lowercase, e.g., us, de, pl).