Defold MCP

A production-quality Model Context Protocol (MCP) server that gives AI coding agents comprehensive control over a local Defold game-development project.

What it does

Defold MCP exposes Defold projects through structured MCP tools so an AI agent can:

• Inspect project structure, settings, and resources
• Read, write, and patch Lua scripts and Defold text resources
• Search across the project
• Analyze Lua scripts and resource dependencies
• Modify collections, game objects, GUI files, and input bindings
• Validate Lua syntax and resource references
• Build and run the project through a local Defold installation
• Parse build errors and diagnostics

Requirements

• Node.js 20+
• A Defold project with a game.project file
• (Optional) Defold editor/CLI for build/run integration

Installation

npm install
npm run build

Running the MCP

node dist/index.js --project "C:\Path\To\Your\Defold\Game"

Or with environment variables:

set DEFOLD_PROJECT_ROOT=C:\Path\To\Your\Defold\Game
set DEFOLD_MCP_LOG_LEVEL=info
node dist/index.js

CLI options

defold-mcp [options]

Options:
  --project <path>      Path to the Defold project root
  --defold-path <path>  Path to the Defold installation/CLI
  --log-level <level>   debug | info | warn | error (default: info)
  --help, -h            Show help
  --version, -v         Show version

MCP client configuration

Claude Code / generic stdio

{
  "mcpServers": {
    "defold": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\defold-mcp\\dist\\index.js",
        "--project",
        "C:\\Path\\To\\MyDefoldGame"
      ]
    }
  }
}

Cursor

Add a new MCP server in Cursor settings pointing to:

• Command: node
• Args: C:\Path\To\defold-mcp\dist\index.js, --project, C:\Path\To\MyDefoldGame

VS Code

Use an MCP extension and configure a stdio server with the command above.

Security model

• The server operates strictly inside the configured project root.
• All paths are resolved and validated against the project root.
• Path traversal, absolute paths outside the project, and symlink escapes are rejected.
• Destructive operations (delete_file, remove_game_object, etc.) require confirm: true.
• No arbitrary shell commands are exposed.
• Only processes started by defold_run can be stopped via defold_stop.

Available tools

Read-only

• defold_get_project — project info and Defold detection
• defold_list_files — list project files and directories
• defold_read_file — read a text file
• defold_search — search project text files
• defold_analyze_lua — analyze a Lua script
• defold_read_collection — read a collection structurally
• defold_dependencies — direct/reverse dependencies of a resource
• defold_project_context — compact AI-friendly project summary
• defold_analyze_project — project-wide analysis and issues
• defold_get_input_bindings — read input bindings
• defold_get_build_errors — parse build output
• defold_git_status — read-only Git status

Write

• defold_write_file
• defold_create_file
• defold_apply_patch
• defold_create_collection
• defold_add_game_object_to_collection
• defold_create_gui
• defold_create_gui_node
• defold_add_input_binding

Dangerous (require confirm: true)

• defold_delete_file
• defold_remove_game_object_from_collection

Build / run

• defold_build
• defold_run
• defold_stop
• defold_list_processes
• defold_get_process_output — read captured stdout/stderr from a running/finished process

Development

npm run dev      # watch build
npm test         # run unit + integration tests
npm run lint     # ESLint
npm run format   # Prettier

Tests

The test suite includes:

• Path security and traversal tests
• Project detection and game.project parsing
• Collection parsing
• Lua editing and patch tests
• File creation and deletion confirmation tests
• Build command and error parsing tests
• Dependency analysis tests
• Optional integration tests that skip if Defold is not installed

Windows notes

• Paths with spaces and backslashes are supported.
• Use Node's cross-platform APIs internally; no bash required.
• Configure --defold-path or DEFOLD_PATH if Defold is not on PATH.

Known limitations

• Defold build integration relies on bob.jar being available. If only the editor executable is present, headless builds are limited.
• Lua analysis is lightweight regex-based; it is not a full AST parser.
• Some advanced Defold features (e.g., complex component properties) may require manual editing.

Debug loop: build → run → inspect

To know whether a change actually works, the AI should follow this loop instead of guessing:

1. defold_build — build the project.
2. defold_get_build_errors — extract errors, warnings, and file/line info.
3. defold_read_file — inspect the offending files.
4. defold_apply_patch — make a focused fix.
5. defold_validate — validate Lua syntax and resource references.
6. defold_run — launch the game.
7. defold_get_process_output — read captured runtime stdout/stderr.
8. Repeat from step 1 until the build succeeds and the game runs cleanly.

defold_get_process_output is the key to confirming the game works: it returns everything the running Defold process prints, including Lua runtime errors, warnings, and print()/pprint() output.

Final acceptance test

The repository includes an automated acceptance path that exercises the core AI workflow:

npm test

This runs the full suite against tests/fixtures/sample-project, which performs:

1. Loads the sample Defold project.
2. Calls defold_get_project / defold_project_context.
3. Finds player/player.script.
4. Reads player/player.script.
5. Applies a focused patch to player/player.script.
6. Validates the project with defold_validate.
7. Builds the project with defold_build if Defold is installed.
8. Parses build results with defold_get_build_errors.
9. Reports changed files and diagnostics.

Recommended next features

• Full game object/component modification tools
• Sprite/atlas/tilesource creation helpers
• Deeper message flow analysis (defold_find_messages)
• Project indexing and caching for large projects
• HTTP/SSE transport support

Author

• GitHub: zrnge/defold-mcp
• Website: zrnge.github.io

License

MIT