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

$3

``bash
npx mcp-ctftime
`

$3

`bash
npm install -g mcp-ctftime
mcp-ctftime
`

$3

`bash
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

$3

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

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

Using global install:

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

Restart Claude Desktop after editing the config.

---

$3

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

Using the CLI:

`bash
codex mcp add ctftime -- npx -y mcp-ctftime
`

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

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

Using global install:

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

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

---

$3

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

`json
{
"amp.mcpServers": {
"ctftime": {
"command": "npx",
"args": ["-y", "mcp-ctftime"]
}
}
}
`

Using global install:

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

Via CLI:

`bash
amp mcp add ctftime npx -y mcp-ctftime
`

---

$3

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

Using npx (recommended):

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

Using global install:

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

Via CLI:

`bash
gemini mcp add ctftime npx -- -y mcp-ctftime
`

Use /mcp in Gemini CLI to verify server status.

---

Docker

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

For clients that support Docker-based MCP servers:

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

---

Compatibility

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

$3

| 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

`bash


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