{"id":50485795,"url":"https://github.com/youssof20/godot-mcp","last_synced_at":"2026-06-01T22:02:34.521Z","repository":{"id":361147179,"uuid":"1253285863","full_name":"youssof20/godot-mcp","owner":"youssof20","description":"MCP server for Godot 4: connect your editor to MCP clients over WebSocket with a focused tool set and structured scene summaries.","archived":false,"fork":false,"pushed_at":"2026-05-29T10:15:58.000Z","size":222,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T12:14:31.731Z","etag":null,"topics":["editor-plugin","game-development","gamedev","godot","godot-4","godot-engine","godot-plugin","mcp","model-context-protocol","type","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/youssof20.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T10:08:50.000Z","updated_at":"2026-05-29T10:28:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/youssof20/godot-mcp","commit_stats":null,"previous_names":["youssof20/godot-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/youssof20/godot-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youssof20%2Fgodot-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youssof20%2Fgodot-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youssof20%2Fgodot-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youssof20%2Fgodot-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youssof20","download_url":"https://codeload.github.com/youssof20/godot-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youssof20%2Fgodot-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33795114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editor-plugin","game-development","gamedev","godot","godot-4","godot-engine","godot-plugin","mcp","model-context-protocol","type","websocket"],"created_at":"2026-06-01T22:02:33.065Z","updated_at":"2026-06-01T22:02:34.514Z","avatar_url":"https://github.com/youssof20.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# godot-mcp\n\nMCP server for **Godot 4** that connects your game project editor to MCP clients over a local WebSocket. The server exposes a focused tool set and returns scene state as structured summaries so clients do not have to guess layout from file names alone.\n\n```\nMCP client  ←stdio→  godot-mcp (Node)  ←WebSocket→  Godot MCP Pro plugin (in your game project)\n```\n\nThis repository is the **Node server and vendored editor plugin**. It is not a Godot game. Open your own project in Godot and install the plugin under `addons/godot_mcp/`.\n\n## Features\n\n- Read and edit scenes, nodes, scripts, signals, and exports from the editor\n- Summarize 2D/3D layout, UI, TileMaps, animation, and assets (`describe_scene`)\n- Run the game and sample runtime state (`watch_game_state`, input simulation)\n- Post-edit checks on script and property changes (syntax, API patterns, Output log)\n- ClassDB lookup (`get_class_doc`) and optional project notes (`project_memory`)\n- Modes: full (~190 tools), **lite** (~98, default), 3D-focused, or minimal\n\nThe server does **not** generate audio, textures, meshes, or subjective \"game feel\" judgments. Provide those assets yourself.\n\n## Requirements\n\n- **Node.js** 18+\n- **Godot** 4.4+ with your game project\n- An MCP-capable client (e.g. Cursor, Claude Desktop, other MCP hosts)\n\n## Quick start\n\n### 1. Build the server\n\n```bash\ngit clone https://github.com/youssof20/godot-mcp.git\ncd godot-mcp\nnpm install\nnpm run build\n```\n\nSmoke test (optional):\n\n```bash\nnpm start\n# Expect: WebSocket listening on ws://127.0.0.1:6505\n```\n\n### 2. Install the Godot plugin\n\nCopy the bundled addon into your game project:\n\n**From:** `vendor/godot_mcp`  \n**To:** `YourGame/addons/godot_mcp`\n\nConfirm these runtime files exist (see `vendor/godot_mcp/REQUIRED_FILES.txt`):\n\n- `mcp_screenshot_service.gd`\n- `mcp_input_service.gd`\n- `mcp_game_inspector_service.gd`\n\nIn Godot: **Project → Project Settings → Plugins** → enable **Godot MCP Pro**.\n\n### 3. Configure your MCP client\n\nPoint the client at `build/index.js`. Example `mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"godot-local\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/godot-mcp/build/index.js\", \"--lite\"]\n    }\n  }\n}\n```\n\nUse forward slashes in JSON paths on Windows. Restart the MCP server after rebuilding.\n\n### 4. Each work session\n\n1. Open your **game** in Godot (plugin enabled).\n2. Start or reload the MCP server in your client.\n3. Call `get_project_info` or `initialize_session` to verify the link.\n\nThe server waits up to 30 seconds for Godot on the first command if the editor was started later.\n\n## MCP modes\n\n| Flag | Approx. tools | Use case |\n|------|----------------|----------|\n| *(none)* | ~190 | Full command surface |\n| `--lite` | ~98 | Daily use (default in sample `mcp.json`) |\n| `--3d` | ~111 | Lite plus physics, navigation, animation tree |\n| `--minimal` | ~45 | Small context windows |\n\nCall `list_available_tools` to see what the current mode exposes.\n\n## Useful tools\n\n| Goal | Tool |\n|------|------|\n| Scope and limits | `get_capabilities` |\n| Session bootstrap | `initialize_session` |\n| Scene layout summary | `describe_scene` (see `action` parameter) |\n| 3D positions | `describe_scene` / `get_spatial_map` |\n| Signals before wiring | `get_signal_graph` |\n| Inspector exports | `get_export_values` |\n| Runtime sampling | `watch_game_state` |\n| Godot 4 API reference | `get_class_doc` |\n| Debug failed calls | `get_mcp_activity_log` |\n\nAfter `edit_script`, `create_script`, or `update_property`, check `post_edit_validation` in the response.\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| Godot not connected | Godot open, plugin enabled, MCP server running; restart both |\n| `get_scene_tree` fails | Open a scene tab or set **Application → Run → Main Scene** |\n| Autoload errors for `mcp_*_service.gd` | Re-copy the entire `vendor/godot_mcp` folder into `addons/godot_mcp` |\n| `get_game_*` fails | Press Play or use `play_scene` with a valid scene path |\n| Port in use | Stop other server instances or set `GODOT_MCP_PORT=6506` |\n\nGodot tries WebSocket ports **6505–6509**. Use the MCP panel in the editor to view activity and connected clients.\n\n## CLI (without an MCP client)\n\n```bash\nnode build/cli.js project get_project_info\n```\n\nGodot must be running with the plugin enabled.\n\n## Versions\n\n| Component | Version |\n|-----------|---------|\n| npm package `godot-mcp-local` | 2.0.0 |\n| Bundled Godot MCP Pro plugin (`vendor/godot_mcp`) | 1.14.1 |\n\nPlugin version in Godot’s plugin list is independent of the npm package version. Both share the same JSON-RPC command set.\n\n## Architecture\n\n- Node listens on `127.0.0.1:6505–6509`\n- The Godot plugin connects outbound to Node\n- JSON-RPC 2.0, 30s command timeout, ping/pong keepalive\n\n## License\n\nThe addon in `vendor/godot_mcp` follows [godot-mcp-pro](https://github.com/youichi-uda/godot-mcp-pro) licensing. This Node server is an independent implementation of the public wire protocol.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoussof20%2Fgodot-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoussof20%2Fgodot-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoussof20%2Fgodot-mcp/lists"}