PicoCTF MCP Server

An open-source MCP (Model Context Protocol) server for CyLab Security Academy — the new platform behind PicoCTF. Lets AI agents browse, solve, and submit CTF challenges programmatically.

This is the first MCP server for the new CyLab Academy platform. PicoCTF recently migrated from their legacy platform to an entirely new one with a different API. No existing integrations or automation tools existed for it — so I built one.

Why This Exists

I was benchmarking how well a locally-hosted LLM (Qwen 3.6 27B on consumer GPUs) (who knew it is fun lol) handles security tasks. Synthetic benchmarks only tell you so much — I wanted real challenges with clear success criteria. PicoCTF was the obvious choice: structured problems, flag-based verification, challenges spanning multiple categories, having used it extensively and most importantly it is built by my Alma mater :)

The MCP server lets any AI agent that supports the Model Context Protocol interact with PicoCTF challenges end-to-end. List challenges, launch instances, download files, solve, submit flags — all through tool calls.

I am releasing it so anyone can:

Benchmark their models on real security challenges
Test refusal behavior — does your model refuse legitimate security tasks? - I am interested in this so reach out with cool results :)
Automate CTF workflows with any MCP-compatible agent (Claude Code, OpenCode, custom harnesses)

Current limitation: hint gating relies on agent-side enforcement, so behavior may vary depending on the MCP client/agent implementation. Future work includes stronger server-side controls

Features

16 tools covering the full challenge lifecycle
Playwright-based auth — persistent browser profile handles Cloudflare, no cookie juggling - learning from the best in class agents :)
Hint stripping — hints hidden by default, forces genuine problem-solving before revealing them one at a time
Full API coverage: challenges, instances, submissions, categories, events, bookmarks, stats

Tools

| Tool | Description | |------|-------------| | picoctf_list_challenges | Browse/filter by category, difficulty, event, search term | | picoctf_get_challenge | Challenge details (hints stripped by default) | | picoctf_launch_instance | Start an instance — PUT + automatic polling until running | | picoctf_get_instance | Check instance status, connection info, time remaining | | picoctf_stop_instance | Stop a running instance | | picoctf_submit_flag | Submit a flag for a challenge | | picoctf_get_hints | Reveal hints (only when stuck) | | picoctf_download | Download challenge files | | picoctf_list_categories | All categories with numeric IDs | | picoctf_list_events | Available events/competitions | | picoctf_get_stats | Gym stats — solved count, breakdown by difficulty/category | | picoctf_get_user | Current user info | | picoctf_bookmark | Bookmark a challenge | | picoctf_unbookmark | Remove bookmark | | picoctf_check_session | Verify auth session is valid | | picoctf_browse_page | Browse any page on the platform |

Setup

Prerequisites

pip install playwright
playwright install chromium

Login (one-time)

Opens a real browser window — log in manually, then close it. The session is saved as a persistent browser profile.

# Set DISPLAY if running on a remote/headless machine (e.g. xrdp) # Might need to experiment with multiple different values if you are running as RDP
export DISPLAY=:0

python3 picoctf_mcp.py --login

Verify

python3 picoctf_mcp.py --test

Run as MCP Server

python3 picoctf_mcp.py

MCP Client Configuration

Add to your MCP client config (Claude Code settings.json, OpenCode opencode.jsonc, etc.):

{
  "mcpServers": {
    "picoctf": {
      "command": [
        "python",
        "/absolute/path/to/picoctf_mcp.py"
      ]
    }
  }
}

NOTE: Different coding agents will have different ways to configure MCP servers

Skill File

The SKILL.md file provides structured instructions for AI agents. Load it as a system prompt or skill file for best results. It covers:

Workflow: list → launch → solve → submit
Hint escalation: try without hints first, then one hint at a time after repeated failures
Reporting: always state whether hints were used and how many
Argument types: strict type table to prevent common model mistakes (string vs int IDs)
Instance management: expiry awareness, restart on timeout
Cleanup: stop instances and delete temp files after each challenge
Sudo escalation: if stuck on a permission issue, ask the user with a clear explanation

How It Works

Cloudflare Bypass

CyLab Academy sits behind Cloudflare, which blocks direct API calls from scripts. We solve this by routing ALL API requests through Playwright's browser fetch() from within a loaded page — this inherits the React auth headers and Cloudflare clearance tokens automatically.

Persistent Browser Profile

Instead of exporting/importing cookies, the MCP uses Playwright's launch_persistent_context with a saved browser profile directory (~/.picoctf_browser_profile/). The headed login session and the headless MCP runtime share the same profile, so auth "just works" across restarts.

Hint Stripping

Hints are replaced with a count message by default:

"hints": "[3 hints available — use show_hints=true to reveal]"

This forces the agent to attempt solving before requesting help, and when it does request hints, the skill file guides it to read them one at a time — not all at once.

API Endpoints

Discovered by intercepting the CyLab Academy React app's network requests:

| Method | Endpoint | Purpose | |--------|----------|---------| | GET | /api/categories/ | List categories | | GET | /api/challenges/?page=&category=&difficulty=&search= | List challenges | | GET | /api/challenges/<id>/ | Challenge details | | PUT | /api/challenges/<id>/instance/ | Start/restart instance | | GET | /api/challenges/<id>/instance/ | Instance status | | DELETE | /api/challenges/<id>/instance/ | Stop instance | | POST | /api/submissions/ | Submit flag {challenge: id, flag: str} | | GET | /api/events/?has_ended=true&has_gym_challenges=true | List events | | GET | /api/gym/stats | Gym statistics | | GET | /api/_allauth/browser/v1/auth/session | Current user session | | PUT | /api/challenges/<id>/bookmark/ | Bookmark | | DELETE | /api/challenges/<id>/bookmark/ | Unbookmark |

Remember

To have fun :)

License

MIT

MCP Servers