demoreel MCP server
Analyzes Counter-Strike 2 demo files to provide match metrics, scoreboards, round and kill data, player statistics, highlight detection, and editable highlight specs. It can render highlights and reels from CS2 matches using in-game POV or radar renderers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@demoreel MCP server show the scoreboard and top highlights from my latest demo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
demoreel
Upload a CS2 demo. Get the match metrics and the highlight videos back — automatically.
demoreel is a self-hosted service that ingests Counter-Strike 2 demos (.dem), computes scoreboard-grade
statistics, detects the moments worth watching, and renders them to video. It is built to be driven by
software as much as by people: a REST API, webhooks, and an MCP server so LLM agents can query a match
and edit its highlights.
┌────────────┐ analyze ┌──────────────────────┐
.dem ────▶ │ REST API │ ───────────▶ │ stats · rounds · kills│ ──▶ JSON (API / MCP / web UI)
upload │ MCP · UI │ job queue │ highlight candidates │
└────────────┘ └──────────┬───────────┘
▲ │ highlight = editable spec
│ edit ops (trim, POV, speed…) ▼ (segments: ticks, POV, speed, caption)
humans / agents ┌──────────────────────┐
│ renderers │ ──▶ mp4 + thumbnail
│ ingame (CS2 POV) │
│ radar (2D replay) │
└──────────────────────┘Status: early (v0.1). Analysis, highlight detection, the API, MCP server, web UI and the 2D renderer work end to end on real demos. The in-game (first-person) renderer has produced correct clips on Windows with the current CS2 build (single and multi-take, from the CLI and through the server), on one machine so far — see what is and is not verified in docs/ingame-recording.md, and the roadmap.
What you get
Match metrics — score by half and side, per-round economy and outcome, and per player: K/D/A, ADR, KAST, HS%, rating (HLTV 2.0 approximation), opening duels, trades, multi-kills, clutches (1vX), utility damage, flashes, accuracy, weapon breakdown, CT/T split.
Automatic highlights — aces and multi-kills, won clutches, flashy single kills (noscope, through smoke, wallbang, blind, airborne, knife, zeus), ninja defuses; each scored and described, with tight clip boundaries (kills far apart become separate segments).
Highlight videos from two renderers:
ingame— the real game, from the player's point of view (needs a PC with CS2);radar— a 2D tactical replay with rosters, kill feed, utility and bomb, which runs anywhere (no game, GPU or display — fine in a container).
Finished, branded videos — give the instance a brand kit (logo + colours) and every video gets an animated intro and outro generated from the logo (with synthesised sound), a HUD in the community's identity (score, nameplate, kill counter), captions and real slow motion. White-label: no third-party watermark. See docs/branding.md.
Ready to post — every play in 16:9 and in 9:16 laid out for phones (and 1:1), cut from the same recorded footage; one call produces a whole match.
Import from your community's site — point a small JSON file at a site that lists matches and demo links, and import a night's games in one click (or one MCP call). Imports are throttled and stop at the first sign that the site is overloaded.
Edits without the game — first-person captures are kept as masters with handles, so trimming, slowing down, captioning or re-branding a clip re-renders in seconds without launching CS2 again.
Editable highlights — a highlight is a small declarative spec. Trim it, change POV, slow it down, add a caption, split or reorder segments through validated operations, then re-render. Reels stitch several highlights into one video.
Agent-friendly by design — MCP tools with compact outputs, job handles you can block on instead of polling, actionable error messages,
/llms.txt, a complete OpenAPI contract.Async everything — uploads and renders return a job; long-poll it or subscribe with webhooks.
One install, no infrastructure — SQLite and a DB-backed queue by default (no Redis). Windows and Linux.
Related MCP server: Botverse
Quick start
Requirements: uv (it brings its own Python). ffmpeg is bundled.
git clone <this-repo> demoreel && cd demoreel
uv sync
uv run demoreel serveOpen http://127.0.0.1:8000, drop a demo, watch the highlights. API docs live at /docs.
No server, just the terminal:
uv run demoreel analyze path/to/match.dem # scoreboard + highlights
uv run demoreel render path/to/match.dem -o reel.mp4 # top highlights as one video
uv run demoreel doctor # what this machine can doDocker (API + worker + 2D renderer): docker compose up --build.
Using the API
# 1. upload → 202 with a match and a job
curl -F "file=@match.dem" http://127.0.0.1:8000/api/v1/matches
# 2. wait for the analysis (long-poll, no busy loop)
curl "http://127.0.0.1:8000/api/v1/jobs/<job_id>?wait=60"
# 3. read
curl http://127.0.0.1:8000/api/v1/matches/<match_id>/scoreboard
curl http://127.0.0.1:8000/api/v1/matches/<match_id>/highlights
# 4. edit a highlight: start 1s later, slow-mo on the final second, add a caption
curl -X POST http://127.0.0.1:8000/api/v1/highlights/<id>/edit -H "content-type: application/json" -d '{
"ops": [
{"op": "trim", "segment": 0, "start_delta_s": 1.0},
{"op": "split_segment", "segment": 0, "at_tick": 74560},
{"op": "set_speed", "segment": 1, "speed": 0.5},
{"op": "set_caption", "segment": 1, "caption": "1v2 on the pistol round"}
]}'
# 5. render → 202 with a job; when done, the render has a video_url
curl -X POST http://127.0.0.1:8000/api/v1/highlights/<id>/renders -H "content-type: application/json" \
-d '{"renderer": "radar"}'Everything else (custom highlights from any tick range, reels, kill search, the plays feed, match sources,
the brand, webhooks, capabilities) is in
the interactive docs at /docs and summarised for machines at /llms.txt.
Using it from an LLM agent (MCP)
The API process serves MCP over Streamable HTTP at /mcp; demoreel mcp speaks stdio for local clients.
# Claude Code, remote/HTTP
claude mcp add --transport http demoreel http://127.0.0.1:8000/mcp
# Claude Code / Claude Desktop, local stdio (run from the repo so it finds the same data dir)
claude mcp add demoreel -- uv run --directory /path/to/demoreel demoreel mcpTools: list_matches, get_match, get_player_stats, list_rounds, get_round, search_kills,
list_highlights, get_highlight, create_highlight, edit_highlight, delete_highlight,
render_highlight, render_reel, get_job, get_render, cancel_job, get_feed, list_source_matches,
import_matches, import_demo, produce_match, get_brand, get_capabilities,
list_nights, get_rivalries, get_player_profile, get_trophies, get_chat_rankings (insights across
matches: who owns whom, each night's trophies, the cry-baby ranking of the chat — see
docs/metrics.md)
— plus a make_highlight_reel prompt and the full analysis as a resource. Then just ask:
"Look at the last match, find biruta's best moment, cut it down to the three kills, slow down the last one and give me the video."
More in docs/agents.md.
Renderers
|
| |
Output | Real CS2 footage, player POV | 2D top-down tactical replay |
Needs | Windows/Linux PC with CS2, GPU, desktop session | Nothing (CPU only) |
Speed | Slow (launches the game) | ~1× real time on a desktop CPU |
Enable |
| Always on |
renderer: "auto" (the default) uses ingame when the server can, otherwise radar. Workers advertise
capabilities, so a Linux server can analyze and render 2D while a gaming PC runs
demoreel worker -c ingame against the same database and records the first-person clips.
Radar images are Valve assets and are not in this repository; they are downloaded on first use from the
awpy-data releases into the data directory
(DEMOREEL_OFFLINE=1 disables that and renders on a plain grid).
Configuration
Environment variables (or a .env file) — see .env.example. The ones you will touch first:
DEMOREEL_DATA_DIR, DEMOREEL_PUBLIC_URL, DEMOREEL_API_KEY, DEMOREEL_AUTO_RENDER_TOP,
DEMOREEL_DEFAULT_RENDERER, DEMOREEL_INGAME_ENABLED.
Security note: with no DEMOREEL_API_KEY the API is open — fine on 127.0.0.1, not on a network.
Demos contain player names and SteamIDs; treat the data directory accordingly.
How it works
Parsing — demoparser2 (Rust) behind a defensive wrapper that handles warm-up, knife rounds and restarts, side swaps, missing events and bots (
analysis/parser.py). A 40-minute match analyzes in ~10 s.Stats —
analysis/stats.py; definitions are documented in the code and in docs/metrics.md.Highlights —
analysis/highlights.py: one candidate per (round, player), scored by kills, speed, flashiness, clutch size and round context.Jobs — a table and an atomic claim query (
jobs.py); worker processes with capabilities, heartbeats, re-queue on worker loss.Rendering — a tiny
Rendererprotocol;radardraws with skia and pipes frames to ffmpeg;ingamedrives CS2 following cs-demo-manager's approach.Front-ends — FastAPI (
api.py), MCP (mcp_server.py), Typer CLI, and a no-build static web UI — all thin layers overservice.py.Composition —
compose/: logo splitting, procedural bumpers and sound, HUD, retiming, masters, final assembly. Capture answers "what did the game look like"; composition answers "what does the video look like".
Architecture notes: docs/architecture.md · brand kits and composition: docs/branding.md · speed and scale: docs/performance.md · UI design rationale: docs/design/frontend-design-plan.md.
Development
uv sync
uv run pytest # tests needing a real demo run only if you put .dem files in demos/
uv run ruff check src testsSee CONTRIBUTING.md. The plan — in particular in-game recording hardening and automatic editing (intro/outro bumpers, per-client/map/situation templates, music, transitions, speed ramps) — is in ROADMAP.md.
Acknowledgements
demoparser2 (MIT) — the demo parser.
cs-demo-manager (MIT) by AkiVer — the in-game recording flow (playback plugin, actions file,
startmoviepipeline) is ported from it.awpy / awpy-data (MIT) — map calibration and radar extraction.
Barlow by Jeremy Tribby (SIL OFL 1.1) — the typeface bundled for videos and UI.
reka-ai/cs2-dem-renderer (MIT) — evidence that this recording technique scales on Linux, and the streaming-encode design the performance plan follows.
Ideas on highlight scoring and recording pitfalls were informed by reading cs2-highlights-maker, CS2-insight-agent and cs-demodesk; no code from those projects is included.
demoreel is not affiliated with Valve. Counter-Strike is a trademark of Valve Corporation.
License
Available Tools
30 toolscancel_jobBDestructive
Cancel a queued or running job.
Inputs: job_id (required). Returns: object
create_highlightA
Create a custom highlight. Three ways: (1) segments = explicit list; (2) start_tick + end_tick (+ pov) for one continuous moment; (3) round_number + player to auto-clip that player's kills in that round. Returns the new highlight (not rendered yet).
Inputs: match_id (required), pov, tags, title, +6 more. Returns: object
delete_highlightADestructive
Delete a highlight definition (its rendered videos are kept).
Inputs: highlight_id (required). Returns: object
edit_highlightA
Edit a highlight with a list of operations applied in order (all-or-nothing). Operations: trim{segment,start_delta_s,end_delta_s} · set_range{segment,start_tick,end_tick} · set_pov{segment|null,steamid} · set_speed{segment|null,speed} · set_caption{segment,caption} · add_segment{start_tick,end_tick,pov_steamid,speed,caption,index} · remove_segment{segment} · move_segment{segment,to} · split_segment{segment,at_tick} · set_meta{title,description,tags}. Segment indexes are 0-based. Example slow-motion on the last second of segment 0 that ends at tick 5000: [{op:'split_segment',segment:0,at_tick:4936},{op:'set_speed',segment:1,speed:0.5}]. Call render_highlight afterwards to produce the new video.
Inputs: ops (required), highlight_id (required). Returns: object
get_brandARead-only
Identity of this instance: the community's name, tagline, site, colours and logo. Videos carry this brand automatically (animated intro/outro built from the logo, HUD, captions); use the name and tone when writing titles or captions.
Inputs: no named parameters. Returns: object
get_capabilitiesBRead-only
Server capabilities: which renderers are available here and why not.
Inputs: no named parameters. Returns: object
get_chat_rankingsARead-only
All-chat rankings for friends to tease each other (a word list, NOT moderation - it misses sarcasm). Podiums: toxic ('boca suja': swearing), whine ('chorão': cheating accusations, luck, complaining), death_cry (whining or swearing within 20 s of his own death - the real cry-baby number), talker ('tagarela': who types the most lines, whatever they say; no examples), laugh ('risadinha'), nice ('gente boa': praise, gg), shouting (caps). Each podium entry has the count, the rate per round played and one or two example lines (slurs masked). players has every count per player.
Inputs: limit, night, since, until, +1 more. Returns: object
get_feedARead-only
The best plays that already have a video, across all matches, best first. Each item has the play (player, kind, round, tags), its match and the video_url. Use it to answer 'show me the best plays' or 'what did do lately' without walking every match.
Inputs: kind, limit, player. Returns: result
get_highlightARead-only
Full highlight: description, every segment (ticks, POV, speed, caption), kill ticks and all its renders. Read this before editing.
Inputs: highlight_id (required). Returns: object
get_jobARead-only
Status of an analysis or render job. wait_seconds blocks until it finishes (max 120) — prefer this over polling in a tight loop.
Inputs: job_id (required), wait_seconds. Returns: object
get_matchBRead-only
Match overview: status, map, teams, scoreboard (K/D/A, ADR, KAST, rating per player) and the top highlights. Start here.
Inputs: match_id (required). Returns: object
get_player_profileBRead-only
One player across matches: matches, wins, K/D/A, ADR, KAST and rating (weighted by rounds), HS%, clutches, opening duels, multi-kills, best plays (highlight ids and scores), fails by kind, nemesis and favourite victim, chat numbers and the last matches. No filter = every match he played.
Inputs: player (required), night, since, until, +1 more. Returns: object
get_player_statsBRead-only
Every stat of one player: rating, ADR, KAST, opening duels, trades, multi-kills, clutches, utility, per-weapon kills, CT/T split.
Inputs: player (required), match_id (required). Returns: object
get_renderCRead-only
A rendered video: status, video_url, thumbnail_url, size, and whether it is stale (highlight edited after rendering).
Inputs: render_id (required). Returns: object
get_rivalriesARead-only
Who kills whom across matches. pairs: two players, kills of each on the other (score, the one ahead first), matches they faced each other, opening kills and knife/Zeus kills of each on the other, imbalance (0 even, 1 one-way). players: each player's nemesis ('carrasco', who beats him the most) and favourite victim ('freguês') as 'name (his kills-his deaths)'. No filter = every match; pass player for one player's rivalries. sort: duels (most kills between them) | diff | imbalance.
Inputs: sort, limit, night, since, +4 more. Returns: object
get_roundBRead-only
Full detail of one round: every kill (tick, weapon, headshot, wallbang, smoke, trade…), clutches, bomb events, economy.
Inputs: match_id (required), round_number (required). Returns: object
get_trophiesARead-only
Trophies of one match (match_id) or one night (night; default: the most recent night): MVP, clutch king, entry fragger, longest kill streak, longest drought, kills on 10 HP or less, friendly flasher, friendly fire, best and worst aim, died with the knife out, baiter, economist, headshot machine. Each has titles in Portuguese and English, the winner, the value, the numbers behind it and the runners-up; a trophy nobody deserved is left out.
Inputs: night, match_id. Returns: object
import_demoA
Analyze a demo file that already exists on the server's disk (inside one of the configured import folders). To upload from elsewhere use the REST API: POST /api/v1/matches (multipart field file). Returns match_id and job_id; wait with get_job, then call get_match.
Inputs: path (required), auto_render_top. Returns: object
import_matchesA
Download and analyze matches from a source (see list_source_matches). Returns one job per match; wait with get_job, whose result carries the new match_id. Matches already imported or without a demo are reported in skipped.
Inputs: source_id (required), remote_ids (required), auto_render_top. Returns: object
list_highlightsARead-only
Highlights of a match, best first, with video URL when rendered. score is 0-100 and tier S/A/B/C; featured plays are the curated best of each team plus stand-out plays - they get first-person videos, the others only 2D replays. get_highlight shows the score breakdown (feat, impact, style, economy, stakes, outcome). Pass featured=true for just the curated ones.
Inputs: match_id (required), kind, limit, player, +2 more. Returns: result
list_matchesBRead-only
List analyzed matches (newest first) with map, score and status.
Inputs: limit, status. Returns: result
list_nightsARead-only
Nights of play, newest first: date, match ids, maps, how many players and rounds. A night is every match from noon to noon, so games after midnight count for the evening before. Use the date as night in get_trophies / get_rivalries / get_chat_rankings / get_player_profile.
Inputs: no named parameters. Returns: result
list_roundsARead-only
One line per round: winner, reason, score, buys, bomb, first kill, tick range. Use get_round for the kill-by-kill detail.
Inputs: match_id (required). Returns: result
list_source_matchesARead-only
Sites this server can import matches from (for example the community's own match history), and for one source the matches it lists with their import status here. Call without source_id to list sources.
Inputs: limit, source_id, only_missing. Returns: object
produce_matchA
Make the videos of a match in one call: 2D replays ('radar') of every highlight and first-person POV ('ingame') of the featured ones - pov='all' records every play instead - in each shape ('16:9', '9:16' ready to post on phones, '1:1'). Videos that already exist and are up to date are skipped. First-person plays without recorded footage are captured together in one game session (capture_job_id, wait with get_job); their videos are queued when it finishes. detail explains anything that could not be queued (for example: recording is not enabled here).
Inputs: match_id (required), pov, force, formats, +2 more. Returns: object
render_highlightA
Render a highlight to an mp4 (asynchronous). renderer: 'auto' (in-game POV if this server can, else 2D), 'radar' (2D tactical replay; extra: {camera:'follow'|'full', zoom:1-3}) or 'ingame' (real CS2 footage, slower). Returns job_id; if wait_seconds > 0 it waits and includes video_url when done.
Inputs: highlight_id (required), fps, extra, width, +3 more. Returns: object
render_reelB
Render a reel: several highlights back to back in one video, with title cards. Pass highlight_ids for an explicit order, or let the server pick the top best (optionally only for one player).
Inputs: match_id (required), fps, top, extra, +7 more. Returns: object
rescore_matchA
Re-run the highlight scoring and curation on a match that is already analyzed (fast, the demo is not read again). Highlights keep their ids and videos; featured plays chosen by hand are kept.
Inputs: match_id (required). Returns: object
search_killsCRead-only
Search the kill log. All filters are optional and combined with AND.
Inputs: match_id (required), limit, victim, weapon, +6 more. Returns: result
set_featuredA
Promote a play to the featured ones (they get first-person videos when the match is produced) or remove it from them. Overrides the automatic curation and survives re-scoring.
Inputs: featured (required), highlight_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools map to clearly distinct resources or actions: matches, rounds, kills, highlights, players, jobs, renders, imports and analytics. A few pairs such as get_player_stats vs get_player_profile and get_feed vs list_highlights need the descriptions to separate them, but the boundaries are still workable.
The tool set uses a consistent snake_case verb_noun pattern throughout: list_matches, get_match, create_highlight, render_reel, import_demo, get_player_profile, and so on. Minor variations like set_featured and produce_match still fit the same predictable convention.
Thirty tools is heavy for an agent-facing surface, even though the server spans demo import, analysis, highlight editing, rendering, jobs and community analytics. Many related operations could be consolidated or grouped, and the size increases selection burden.
The surface covers the domain well: importing demos and source matches, match/round/kill/player analysis, highlight CRUD, featured curation, rendering, job status, feeds, trophies, rivalries and chat rankings. Minor gaps remain, such as no direct upload tool, no match deletion/metadata management, and limited source administration.
Maintenance
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to query the FACEIT platform for players, matches, hubs, and tournaments through typed MCP tools generated from the FACEIT Data API v4.64MIT
- AlicenseAqualityCmaintenanceMCP tools for video transcoding, document conversion, and multi-step pipelines — callable by any AI agent.1260 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform deterministic video editing operations like trim, resize, add text, and more using MCP tools.5 npm5MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM agents to drive a self-hosted video toolkit through MCP tools, including lipsync, face restoration, ffmpeg operations, and metadata retrieval.1Do What The F*ck You Want To Public