defold-mcp

An MCP server that gives AI coding agents full control over Defold game engine projects — inspect, scaffold, edit, build, run, and test.

An MCP (Model Context Protocol) server that gives AI coding agents — Claude Code, OpenCode, and Codex — full control over a Defold game engine project. It lets an agent inspect a project, scaffold brand-new projects, write scripts, edit collections, build with bob.jar, run the game headlessly, and run a Lua test suite — all over a local stdio connection.

defold-mcp is a Node.js / TypeScript ESM server. It is a local development tool: it talks to your Defold project on disk and shells out (only) to java -jar bob.jar and dmengine_headless. There is no HTTP/SSE transport and no authentication — it is intended strictly for local use.

Table of Contents

• 🎮 Overview

• ✨ Features

• 📦 Install / Build

• ⚙️ Environment Variables

• 🔌 MCP Client Registration

• 🛠️ Tools Reference

• ✅ Test Script Convention

• ⚠️ Known Limitations

• 🗺️ Roadmap

• 🤝 Contributing

• 📄 License

Related MCP server: Forge Engine MCP Server

🎮 Overview

An MCP (Model Context Protocol) server that gives AI coding agents — Claude Code, OpenCode, and Codex — full control over a Defold game engine project. It lets an agent inspect a project, scaffold brand-new projects, write scripts, edit collections, build with bob.jar, run the game headlessly, and run a Lua test suite — all over a local stdio connection.

defold-mcp is a Node.js / TypeScript ESM server. It is a local development tool: it talks to your Defold project on disk and shells out (only) to java -jar bob.jar and dmengine_headless. There is no HTTP/SSE transport and no authentication — it is intended strictly for local use.

✨ Features

A quick glance at the 10 tools the server exposes:

• Inspect project config & file tree

• Read / write scripts and files

• Scaffold new Defold projects

• Edit collections (objects/components/props)

• Build with bob.jar

• Run the game headlessly

• Run a Lua test suite

• Hot reload (experimental)

📦 Install / Build

Requirements:

• Node.js 20+

• A Defold project (a directory containing game.project), or let the server scaffold one with defold_init_project.

• bob.jar and dmengine_headless must be provided by you (see below). They are not bundled.

npm install      # install dependencies
npm run build    # compile TypeScript -> dist/ (runs tsc)
npm start        # run the stdio MCP server (node dist/index.js)

For development without a build step:

npm run dev      # run directly from source (tsx src/index.ts)

npm start is what MCP clients launch. It runs node dist/index.js, which is the built stdio server entrypoint.

⚙️ Environment Variables

The server is configured entirely through environment variables. DEFOLD_PROJECT_PATH is the only commonly required one; the build/run tools degrade gracefully to clear errors if BOB / DMENGINE_HEADLESS are absent.

DEFOLD_PROJECT_PATH=/home/you/projects/my-defold-game
BOB=/opt/defold/bob/bob.jar
DMENGINE_HEADLESS=/opt/defold/bin/x86_64-linux/dmengine_headless

🔌 MCP Client Registration

Register defold-mcp with your MCP client as a stdio server. The command launches node with the built entrypoint dist/index.js as its single argument. Replace the placeholder paths with real absolute paths on your machine.

Add to your project's .mcp.json (or configure globally via claude mcp add):

{
  "mcpServers": {
    "defold": {
      "command": "node",
      "args": ["/abs/path/to/defold-mcp/dist/index.js"],
      "env": {
        "DEFOLD_PROJECT_PATH": "/abs/path/to/your-defold-project",
        "BOB": "/abs/path/to/bob.jar",
        "DMENGINE_HEADLESS": "/abs/path/to/dmengine_headless"
      }
    }
  }
}

Add to ~/.config/opencode/opencode.json (or a project-local .opencode.json):

{
  "mcpServers": {
    "defold": {
      "command": "node",
      "args": ["/abs/path/to/defold-mcp/dist/index.js"],
      "env": {
        "DEFOLD_PROJECT_PATH": "/abs/path/to/your-defold-project",
        "BOB": "/abs/path/to/bob.jar",
        "DMENGINE_HEADLESS": "/abs/path/to/dmengine_headless"
      }
    }
  }
}

Add to ~/.codex/config.toml (or a project-local codex.config.toml):

[[mcp_servers]]
name = "defold"
command = "node"
args = ["/abs/path/to/defold-mcp/dist/index.js"]

[mcp_servers.env]
DEFOLD_PROJECT_PATH = "/abs/path/to/your-defold-project"
BOB = "/abs/path/to/bob.jar"
DMENGINE_HEADLESS = "/abs/path/to/dmengine_headless"

🛠️ Tools Reference

✅ Test Script Convention

Test scripts are ordinary Defold Lua scripts (.script / .lua) that run under the headless engine. To report results, print lines in one of these two exact formats:

PASS: <test_name>
FAIL: <test_name>: <reason>

Examples:

print("PASS: player_spawns_at_origin")
print("FAIL: inventory_adds_item: expected 1 item, got 0")

defold_run_tests collects every PASS:/FAIL: line from the engine log and returns {passed, failed, details:[{name, status, message?}]}. Any line that does not match the convention is ignored. If the build step fails, tests are not run and buildErrors is returned in the result.

⚠️ Known Limitations

• Collection parser is a custom brace-delimited implementation, not a full protobuf schema. It parses and serializes the Defold protobuf-text .collection / .go format (key { ... } blocks and key: value scalars) and is verified by round-tripping real-format samples. It is not a complete protobuf round-trip; re-build and visually verify after any collection edit.

• Hot reload is experimental. The Defold engine service protocol is version-dependent and undocumented; it will likely fail on many setups. The tool always falls back to a clear structured message — use defold_build + relaunch instead.

• bob.jar and dmengine_headless are not bundled. The server requires you to provide them (see Environment variables). If missing, the build/run/test tools return clear errors instead of crashing.

• Stdio only. No HTTP/SSE transport. No authentication — intended strictly as a local development tool.

🗺️ Roadmap

All planned v1 tools are implemented.

🤝 Contributing

Issues and pull requests are welcome. If you'd like to contribute, open an issue to discuss the change first for anything substantial. By contributing you agree your contributions are licensed under the terms of the MIT License.

📄 License

defold-mcp is released under the MIT License. See the LICENSE file for the full text.