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).