convez.ai
MCP Server
BenDaSpur

openrct2-mcp

BenDaSpur/openrct2-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for AI control of a running OpenRCT2 park

Instalação

$npx convez-ai BenDaSpur/openrct2-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

OpenRCT2 MCP AI Park Control

Tests

Bridge a running OpenRCT2 game to Cursor (or any MCP client) so AI agents can read park state, optimize parks, and build roller coasters.

Quick links: License · Issues · Third-party notices

Prerequisites

  • OpenRCT2 0.5.x with RCT2 game files installed
  • Python 3.11+
  • Node.js 18+ (plugin packaging only)

This repo was tested against OpenRCT2 v0.5.1 on macOS.

Quick setup

# 1. Install Python deps + openrct2-bridge plugin
chmod +x scripts/*.sh
./scripts/install-bridge.sh

# 2. Install ride-builder coaster plugin
./scripts/build-plugins.sh

# 3. Launch OpenRCT2, load a park save
#    Check the in-game console for:
#      - Bridge port (starts at 20020)
#      - Ride-builder port (starts at 20021)

# 4. Verify connections (with OpenRCT2 running and a park loaded)
./scripts/check-connection.sh

# Optional: automated headless smoke test
.venv/bin/python scripts/verify-e2e.py

Cursor MCP

Project MCP config lives at .cursor/mcp.json (portable template: .cursor/mcp.json.example). Paths use ${workspaceFolder} and set PYTHONPATH to mcp-server/ so python -m openrct2_mcp resolves without a global install. Copy or adapt the example if your editor does not expand ${workspaceFolder}.

Reload MCP servers in Cursor after OpenRCT2 is running with a loaded park.

Note: End-to-end tools (live park mutations, vision capture, coaster placement) require a running OpenRCT2 instance with plugins loaded. CI runs offline unit tests only.

Example prompts:

  • "Use openrct2_status, then get_park_overview and suggest three improvements."
  • "List rides sorted by excitement and close the worst performer."
  • "Build a small wooden coaster: coaster_create, then loop coaster_get_valid_pieces / coaster_place_piece until the circuit completes."

Architecture

Cursor AI  --MCP-->  Python MCP server  --TCP-->  openrct2-bridge (park ops)
                                              `--TCP-->  ride-builder (coasters)
ComponentRole
openrct2-bridge82 game actions, 77 state queries via pyrct2
ride-builder.jsCoaster-specific TCP API (valid pieces, place track, test ratings)
mcp-server/openrct2_mcpCurated MCP tools wrapping both plugins

MCP tools

Park optimization

ToolDescription
openrct2_statusConnection health for bridge + ride-builder
get_park_overviewRating, guests, cash, scenario objective
list_ridesAll rides with ratings and profit (fast per-ride queries)
get_rideOne ride by id
get_park_messagesComplaints and awards
get_guestOne guest by entity id
list_guestsGuest count by default; full_scan=true for samples (slow)
place_flat_ridePlace flat rides (e.g. gentle.MERRY_GO_ROUND)
place_stallPlace stalls (e.g. stall.DRINKS_STALL)
manage_pathsPaths, queues, benches, bins
manage_staffHire staff, list, set patrol/orders (by staff_id)
list_staff_tool / set_staff_patrol_toolPer-staff patrol management
assign_staff_to_path_corridor_toolPatrol box covering path tiles
optimize_staff_coverage_toolHire + assign staff along main paths
park_health_report_toolComplaints, low satisfaction, recommendations
get_map_bounds_tool / get_map_region_toolPark-scale spatial grids
get_path_graph_tool / find_buildable_loop_toolPath graph and build surveys
apply_theme_preset_toolTheme along paths (see themes/cute.json)
place_small_scenery_tool / paint_terrain_toolDecoration and terrain
set_ride_price / open_ride / close_rideRide operations
refurbish_ride_toolRenew a ride (resets age/reliability; closes and waits for guests by default)
set_park_settingsEntrance fee, open/close park
advance_timeStep simulation ticks
get_researchResearch state

Coaster building

ToolDescription
coaster_createStart a new coaster shell
coaster_get_valid_piecesLegal next track pieces
coaster_place_piecePlace validated track (z_is_train_entry for endpoint Z)
coaster_place_next_piecePlace next piece from valid endpoint (Z-safe)
coaster_build_perimeterBuild flexible perimeter loop along guide ring (detours around obstacles)
coaster_obstacle_map_toolPerimeter obstacle heatmap (paths, track, scenery, slopes, unowned ring stats)
coaster_plan_route_toolDry-run simulate route (probe+undo, no permanent build)
coaster_plan_ahead_toolBeam search 2–4 pieces ahead
coaster_prepare_corridor_toolBuy/clear/flatten along guide corridor (dry_run default)
coaster_track_context_tool / coaster_full_track_context_toolEndpoint context with height + collisions
get_tile_height_tool / coaster_site_survey_toolGround tile_z, slope, flat build sites near x,y
coaster_height_context_tool / coaster_probe_piece_toolZ vs ground; per-piece collision probe
coaster_start_track_toolCreate coaster + BeginStation at surveyed tile
coaster_rank_next_pieces_toolRank pieces by clearance, height fit, and collisions
coaster_undoRemove last piece
coaster_finish_stationPlace entrance/exit
coaster_testTest ride and return ratings
coaster_statsCurrent excitement/intensity/nausea
coaster_deleteDemolish coaster
list_loaded_ride_objectsValid ride object indices

Coaster workflow

  1. list_loaded_ride_objects — pick a valid ride_object index
  2. coaster_site_survey_tool(x, y) — find flat tile_z and nearby obstacles
  3. coaster_start_track_tool(x, y) or coaster_create + manual station placement
  4. Loop: coaster_rank_next_pieces_tool or coaster_probe_piece_tool → coaster_place_next_piece
  5. When circuit completes: coaster_finish_station → coaster_test

Use get_tile_height_tool for a single tile; coaster_height_context_tool for endpoint Z vs ground.

Perimeter coaster workflow

  1. coaster_obstacle_map_tool(inset=18) — survey ring clearance and unowned tiles on the guide ring
  2. coaster_plan_route_tool(inset=18) — simulate trace without building
  3. Optional: coaster_prepare_corridor_tool(dry_run=true) then apply with confirm_destructive=true
  4. coaster_build_perimeter(dry_run=true) → coaster_build_perimeter — execute build

Terminal debug (no MCP): .venv/bin/python scripts/plan-coaster-route.py --simulate --inset 18

Vision (screenshots + spatial context)

The MCP server can see the park window while also returning structured map data.

ToolWhat it does
capture_game_viewScreenshot of the OpenRCT2 window (returned as an MCP image)
inspect_area_at_tileASCII path/queue grid + nearby rides + optional screenshot

Recommended build loop:

  1. inspect_area_at_tile(39, 44) — Triple Corkscrew entrance area (example)
  2. Plan paths / queue / ride placement from ASCII map + screenshot
  3. Apply changes via manage_paths, place_stall, coaster_*, etc.
  4. capture_game_view — verify visually

macOS setup: System Settings → Privacy & Security → Screen Recording → enable Cursor (and Terminal if testing from CLI). Without this, tools fall back to text-only context.

Set OPENRCT2_VISION_MAX_WIDTH=1280 (default) to limit screenshot size.

Agent skill

See skills/openrct2-park-director/SKILL.md for orchestration workflows (perimeter coasters, cute themes, staff patrol).

Reload ride-builder after updates: ./scripts/build-plugins.sh then restart OpenRCT2 (plugin loads at launch).

Ride operations (P6)

ToolDescription
set_ride_inspection_interval_toolInspection every 10–120 minutes
set_ride_mode_tool / set_num_trains_tool / set_cars_per_train_toolThroughput tuning
optimize_ride_throughput_toolComposite fix for struggling rides (dry_run supported)
demolish_ride_toolDemolish any ride (confirm_destructive=true)
manage_pathsNow supports remove_tile and remove_line

Land, finance, guests (P7–P9)

ToolDescription
find_open_land_tool / terraform_region_tool / buy_land_tool / clear_area_toolLand survey and terraforming
get_finance_summary_tool / optimize_park_pricing_tool / start_marketing_campaign_toolBusiness loop
fund_research_tool / scenario_progress_toolResearch and objectives
get_complaint_hotspots_tool / guest_flow_summary_toolGuest intelligence

Advanced building and safety (P10–P11)

ToolDescription
coaster_build_along_path_tool / import_track_design_toolPath-following coasters, clipboard designs
place_ride_at_best_tile_tool / extend_queue_toolSmart placement
pre_change_snapshot_tool / get_action_log_toolSafety checkpoints and action journal
Destructive toolsRequire confirm_destructive=true; composites support dry_run=true

Performance

Large parks (1000+ guests, many rides) make bulk bridge queries slow or prone to timeout.

The MCP server avoids the worst patterns:

Slow (avoid)Fast (used instead)
rides (all at once)listAllRides + rides?id=N per ride
guests (all peeps)park.guests count + get_guest(id)
game.state.park() for overviewScalar park.name, park.rating, park.cash, …
Tile-by-tile map scansNot exposed via MCP (too many round-trips)
Footpath scan (fill benches/bins)get_elements_by_type("footpath") bulk first; tile chunk fallback

list_guests defaults to guest count only. Pass full_scan=true only if you accept a long wait.

Reload the MCP server after pulling performance updates.

Configuration

Environment variables (set in .cursor/mcp.json):

VariableDefaultPurpose
OPENRCT2_BRIDGE_PORT20020Bridge plugin TCP port
OPENRCT2_RIDE_BUILDER_PORT20021Ride-builder TCP port
OPENRCT2_BRIDGE_TIMEOUT30Per-request bridge timeout (seconds)
OPENRCT2_RIDE_BUILDER_TIMEOUT15Per-request ride-builder timeout (seconds)

OpenRCT2 config.ini recommendations:

  • macOS: ~/Library/Application Support/OpenRCT2/config.ini
  • Linux: ~/.config/OpenRCT2/config.ini

Override the user data directory with OPENRCT2_USER_PATH (used by install-bridge.sh).

[plugin]
enable_hot_reloading = true

install-bridge.sh enables hot reloading automatically.

Contributing

  1. ./scripts/install-bridge.sh — Python venv, bridge plugin, hot reload
  2. ./scripts/build-plugins.sh — ride-builder plugin
  3. pytest mcp-server/tests -q — offline unit tests (no OpenRCT2 required)
  4. .venv/bin/python scripts/verify-e2e.py — optional smoke test with OpenRCT2 running

Development

# Run MCP server manually
export PYTHONPATH=mcp-server
.venv/bin/python -m openrct2_mcp

# Rebuild ride-builder after edits
./scripts/build-plugins.sh
# Reload plugin in-game (hot reload) or restart OpenRCT2

Safety notes

  • Building tools pause the game before mutations.
  • build_in_pause_mode cheat is enabled on connect for automation.
  • Coaster tools require the ride-builder plugin; park tools require openrct2-bridge.

License

MIT. See NOTICE for third-party attribution. Ride-builder plugin derived from openrct2-ridecreation-api.

Ver o original no GitHub

Relacionados