CS2 Map MCP — AI that builds Counter-Strike 2 maps

CS2 Map MCP is an MCP server that lets AI agents — Claude Code, Claude Desktop, Codex or any MCP client — build complete Counter-Strike 2 maps: geometry, materials, lighting, entities, gameplay mechanics and cs_script scripts. It writes Source 2 map files into a CS2 addon, compiles them with Valve's own resourcecompiler, loads the map in CS2, plays it with real input, looks at the screenshots and fixes what is wrong. When the map is ready, it packs it into its own addon for the Steam Workshop.

Version 1.0. Every feature below was checked in the real game: built through MCP calls, compiled by Valve's tools, loaded in CS2 and looked at. Base commands cover almost everything a mapper does by hand; the quick generators of houses and streets have one look so far (Inferno-like), other looks come from your own styles.

Contents: Gallery · How it works · Install · Prompts to start · Your maps in CS2 and Hammer · Publish to the Workshop · When something goes wrong · Feedback · What it can do · Tools

Gallery

Unedited in-game screenshots. Every map was built only through MCP tool calls.

A cozy courtyard with abilities, hide and seek and own UI (p10_showcase, one batch with an own style):

| | | | --- | --- | | | | | A fountain (revolve), bevelled benches (edit_mesh), house fronts in the own style warm_corte, golden-hour light | A pergola of twisted stone columns (edit_mesh twist), wooden beams, a café with string lights | | | | | Mid double jump: the ability HUD (glass theme), the hide-and-seek HUD (paper theme) and an own title card | The lane with the drivable car; a teleport from its end leads behind a secret wall |

An Inferno-like defuse quarter (p7_quartiere) and outdoor scenes:

| | | | --- | --- | | | | | Bomb site A: arcade, red-brick square, potted lemon trees | Mid street: tinted Inferno plaster fronts, wear decals, street life, warm Inferno light | | | | | Street and houses on terrain | Harbor: water to the horizon, pier, backdrop |

Mechanics through code (p8_mechanics, p9_playground):

| | | | --- | --- | | | | | A drivable off-road car: ray-cast suspension takes kerbs, rocks and slopes; speed-sensitive steering, chase and cabin cameras | A turret on a roof shooting the race drone: yaw/pitch limits, overheating, safe exit | | | | | The railgun: hold to charge, it pierces walls across the map, a glowing beam that fades, spring recoil | A rocket launcher on a Nova base: homing rockets that explode (radius, falloff, knockback) | | | | | Own weapon models held in the hands: the railgun is built on the AWP's skeleton | A physics drone flown from a remote: 50 HP, exact hitbox, chase camera | | | | | A shooting gallery: pop-up targets, score, time and record on the HUD | A bell tower with a dome and windows from base primitives (revolve, cut, vertex blend) |

How it works

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/how-it-works-dark.svg"> <img alt="The AI client calls the cs2map server over MCP; the server writes map files into a CS2 addon; Valve's resourcecompiler builds them; CS2 loads the map; screenshots, console output and test results go back to the AI" src="docs/images/how-it-works-light.svg" width="800"> </picture>

The AI works with files, not with Hammer's UI. It plans the map, edits it in batches of operations, builds it, then checks the result in CS2 (screenshots, real-input scenarios, walking routes, bot matches), fixes what is wrong and builds again. You can open any map in Hammer and edit it by hand at any time.

Install

You need: Windows 10/11 · Counter-Strike 2 with CS2 Workshop Tools (free DLC: Steam → CS2 → Properties → DLC) · Python 3.14 (64-bit) · Blender 4.5 or 5.x (free on Steam; for own models and prop previews) · an MCP client (Claude Code, Claude Desktop, Codex CLI or the Codex app). Optional: Node.js (offline tests of mechanics scripts), Source2Viewer CLI (prop previews; setup offers to download it).

git clone https://github.com/Rmgs123/cs2-map-mcp.git
cd cs2-map-mcp
powershell -ExecutionPolicy Bypass -File .\setup.ps1          # checks everything, shows the plan, changes nothing
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -Apply   # installs and registers the server in your AI clients

setup.ps1 creates the Python environment, finds CS2, Workshop Tools, Blender and Source2Viewer (downloads only after you agree, checked by SHA-256) and registers the cs2map server for Claude Code, Claude Desktop and Codex, backing up each config first. Running it again is safe. Restart your AI client afterwards. An AI agent can do the install for you: ask it to follow docs/INSTALL.md.

Another CS2 path, addon name, Blender path or disk limits: copy config/settings.example.json to config/settings.json and edit it.

Prompts to start

Talk to your AI as you would to a level designer. A few prompts that work well:

Call status and tell me what is missing for CS2 map work.

Build a small 2v2 wingman map in an Italian old-town style: two bomb sites and a mid street.
Compile it, check the timings from both spawns and show me screenshots from above and from each site.

Make a story map: I wake up in a warehouse, find a switch, a door opens and a 60-second timer starts.
Test the whole story with script_test and show me the frames.

Add a drivable car in the yard, a turret on the roof and a rocket launcher on a table. Test each one in the game.

Turn the photos in my/inbox into a "nordic harbour" style, save it, then build a street in that style.

Something looks wrong: run check_map and visual_check, fix everything and show me before/after frames.

The map is done. Prepare it for the Steam Workshop and tell me how to upload it.

If any tool failed or something was missing, write it down with my_notes kind feedback.

Tips: ask for frames from above, from the side and at eye level; ask it to save what it learned (my_notes) so the next chat starts smarter; for big maps work room by room and rebuild often.

Your maps in CS2 and Hammer

• Your maps live in the project addon mcp_lab (change it in config/settings.json): sources in …/Counter-Strike Global Offensive/content/csgo_addons/mcp_lab/maps/, compiled maps in …/game/csgo_addons/mcp_lab/maps/.
• The AI starts CS2 Workshop Tools by itself when it needs the game. To open the addon yourself: Steam → Counter-Strike 2 → Launch CS2 Workshop Tools → choose mcp_lab → Launch Tools. From the Asset Browser you can open any map in Hammer.
• Edit a map in Hammer if you like; save and close it before the AI writes it again (it refuses to touch a map with unsaved changes). Every write keeps a backup (map_backups restores one).
• Do not use the game window while the AI runs a script_test: it sends real keys and mouse input.

Publish your map to the Steam Workshop

The project addon holds every map you made, and the Workshop Manager uploads a whole addon. So ask your AI to prepare the release:

1. It runs map_build("<map>", "release"): the map and only the files it uses go into a new addon named like the map, every resource is compiled there, the map gets the final light, a radar and a loading picture.
2. It checks the release itself in the game (game_screenshot(map="<map>/<map>")) and gives you the steps from PUBLISH.md.
3. You upload it. In CS2 Workshop Tools open the Asset Browser → menu Tools → Tools → Counter-Strike 2 Workshop Manager → New:
   • title and description (how to play, the keys of the mechanics);
   • preview image: the map's loading picture (16:9, the path is in PUBLISH.md);
   • addon folder: the new addon named like the map — not mcp_lab, which holds every test map;
   • game mode tags (Classic, Deathmatch, Wingman, Arms Race, Custom) and visibility (Hidden first, then Friends only, then Public);
   • Submit. The first upload asks you to accept the Steam Workshop agreement.

After changes, ask your AI for the release again, then select the map in the Workshop Manager and press Re-Upload.

When something goes wrong

• Ask your AI first. It can run status (CS2, Workshop Tools, Blender, jobs), job_status (build logs), check_map, visual_check and game_crash_report (reads CS2's crash dump).
• CS2 does not respond (the window says "Not responding" for about 30 s): close it yourself and start CS2 Workshop Tools again. The server never kills the game.
• "one console client at a time": a VConsole window holds the game console; the server closes it, or close it yourself.
• A map is refused: it is open in Hammer with unsaved changes — save or close it.
• More causes and fixes: REPAIR.md. After a CS2 update, tools\python-env\Scripts\python.exe tools\selfcheck.py builds a small map with every mechanic and plays it (report in logs/).

Feedback

Your AI keeps a short log of real problems it met with this MCP — a tool error it did not cause, a guide that was wrong, a feature it had to build by hand — in my/feedback.md (it stays on your computer). Send that file to the author or paste it into an issue: it is exactly what the next version is built from. Ideas for new features are welcome too.

What it can do

• Maps without Hammer. A lossless VMAP/DMX codec: 22 of 22 Valve maps round-trip byte for byte. Atomic batch edits, a backup before every write, and undo.
• Any shape. Meshes with concave faces and holes, sweeps along paths and arcs, lathe forms, cutting openings, and edit_mesh — extrude, inset, bevel, subdivide, bend, twist, taper, noise, smooth, mirror on any mesh, with Hammer-like smoothed normals. Per-face material, UV, tint and two-material vertex blending.
• **Q