unity-api-mcp

<!-- mcp-name: io.github.Codeturion/unity-api-mcp -->

MCP server that gives AI agents accurate Unity API documentation. Prevents hallucinated signatures, wrong namespaces, and deprecated API usage.

Supports Unity 2022 LTS, 2023, and Unity 6 with separate databases for each version. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool. No Unity installation required.

Quick Start

Add to your MCP config (.mcp.json, mcp.json, or your tool's MCP settings), setting UNITY_VERSION to match your project:

{
  "mcpServers": {
    "unity-api": {
      "command": "uvx",
      "args": ["unity-api-mcp"],
      "env": {
        "UNITY_VERSION": "2022"
      }
    }
  }
}

Valid values: "2022", "2023", or "6".

On first run the server downloads the correct database (~18-24 MB) to ~/.unity-api-mcp/.

How It Works

1. Version detection. The server figures out which Unity version to serve:

1. Database download. If the database for that version isn't cached locally, it downloads from GitHub (one time).

1. Serve. All tool calls query the version-specific SQLite database. Every query returns in <15ms.

Each version has its own database with the correct signatures, deprecation warnings, and member lists for that release.

Tools

Coverage

All UnityEngine and UnityEditor modules, plus packages parsed from C# source: Input System, Addressables, uGUI, TextMeshPro, AI Navigation, and Netcode.

Does not cover third-party assets (DOTween, VContainer, Newtonsoft.Json). For those, rely on project source.

Benchmarks

In a 10-step research workflow, MCP uses 4x fewer tokens than a skilled agent and 11x fewer than a naive agent:

The gap holds across every question type. MCP wins on simple lookups and complex multi-part research alike:

Even in a realistic hybrid workflow where MCP results are followed up with targeted file reads, it still uses 54% fewer tokens than a skilled agent working without MCP:

"Without MCP" estimates assume full file reads. A skilled agent with good tooling may use fewer tokens than shown. What MCP guarantees is a correct, structured answer in 1 call every time.

Per-question breakdown

<details> <summary>Accuracy</summary>

Ranking uses BM25 with tuned column weights (member name 10x, class name 5x) plus core namespace boosting to ensure Object.Instantiate ranks above niche APIs like InstantiationParameters.Instantiate.

</details>

CLAUDE.md Snippet

Add this to your project's CLAUDE.md (or equivalent instructions file). This step is important. Without it, the AI has the tools but won't know when to reach for them.

## Unity API Lookup (unity-api MCP)

Use the `unity-api` MCP tools to verify Unity API usage instead of guessing. **Do not hallucinate signatures.**

| When | Tool | Example |
|------|------|---------|
| Unsure about a method's parameters or return type | `get_method_signature` | `get_method_signature("UnityEngine.Tilemaps.Tilemap.SetTile")` |
| Need the `using` directive for a type | `get_namespace` | `get_namespace("SceneManager")` |
| Want to see all members on a class | `get_class_reference` | `get_class_reference("InputAction")` |
| Searching for an API by keyword | `search_unity_api` | `search_unity_api("async load scene")` |
| Checking if an API is deprecated | `get_deprecation_warnings` | `get_deprecation_warnings("FindObjectOfType")` |

**Rules:**
- Before writing a Unity API call you haven't used in this conversation, verify the signature with `get_method_signature`
- Before adding a `using` directive, verify with `get_namespace` if unsure
- Covers: all UnityEngine/UnityEditor modules, Input System, Addressables
- Does NOT cover: DOTween, VContainer, Newtonsoft.Json (third-party)

Setup Details

<details> <summary>Auto-detect version from project path</summary>

Instead of setting UNITY_VERSION, you can point to your Unity project. The server reads ProjectSettings/ProjectVersion.txt automatically:

{
  "mcpServers": {
    "unity-api": {
      "command": "uvx",
      "args": ["unity-api-mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/your/unity-project"
      }
    }
  }
}

</details>

<details> <summary>Alternative installation methods</summary>

Using pip install:

pip install unity-api-mcp

{
  "mcpServers": {
    "unity-api": {
      "command": "unity-api-mcp",
      "args": [],
      "env": {
        "UNITY_VERSION": "2022"
      }
    }
  }
}

</details>

<details> <summary>Environment variables</summary>

</details>

<details> <summary>Building databases locally</summary>

If you want to build a database from your own Unity installation instead of downloading:

# Install with ingest dependencies
pip install unity-api-mcp[ingest]

# Build for a specific version
python -m unity_api_mcp.ingest --unity-version 6 --unity-install "D:/Unity/6000.3.8f1" --project "F:/Unity Projects/MyProject"
python -m unity_api_mcp.ingest --unity-version 2022 --unity-install "D:/Unity/2022.3.62f1"
python -m unity_api_mcp.ingest --unity-version 2023 --unity-install "D:/Unity/2023.1.22f1"

Databases are written to ~/.unity-api-mcp/unity_docs_{version}.db by default.

</details>

<details> <summary>AI-Assisted Setup</summary>

If an AI agent is setting this up for you:

Add unity-api-mcp to my MCP config using uvx with UNITY_VERSION set to match my project, append the CLAUDE.md snippet from the README, and verify with get_namespace("SceneManager").

</details>

<details> <summary>Project structure</summary>

unity-api-mcp/
├── src/unity_api_mcp/
│   ├── server.py          # MCP server (5 tools)
│   ├── db.py              # SQLite + FTS5 database layer
│   ├── version.py         # Version detection + DB download
│   ├── xml_parser.py      # Parse Unity XML IntelliSense files
│   ├── cs_doc_parser.py   # Parse C# doc comments from package source
│   ├── unity_paths.py     # Locate Unity install + package dirs
│   └── ingest.py          # CLI ingestion pipeline
└── pyproject.toml

Databases are stored in ~/.unity-api-mcp/ (downloaded on first run).

</details>

Troubleshooting

See Also

[unreal-api-mcp](https://github.com/Codeturion/unreal-api-mcp) — Same concept for Unreal Engine (C++). Covers UE 5.5, 5.6, and 5.7.

Contact

Need a custom MCP server for your engine or framework? I build MCP tools that cut token waste and prevent hallucinations for AI-assisted game development. If you want something similar for your team's stack, reach out.

[email protected]

License

PolyForm Noncommercial 1.0.0

Free to use, fork, modify, and share for any personal or non-commercial purpose. Commercial use requires permission.