unreal-project-mcp

Project-level source and configuration intelligence for Unreal Engine AI development via Model Context Protocol.

Indexes your UE project's C++ source code, config/INI files, Build.cs dependencies, plugin descriptors, gameplay tags, replication topology, asset references, and log categories into a SQLite database. Exposes 17 MCP tools for AI coding assistants like Claude Code — structural queries, config lookups, dependency graphs, and full-text search across your entire project.

Why?

AI assistants are great at writing code but struggle to understand large codebases. This server gives them structural awareness of your project — what calls what, how classes relate, where symbols are used, what config drives behavior, how modules depend on each other — so they can make informed changes instead of guessing.

Complements (does not replace):

• unreal-source-mcp — Engine-level source intelligence (full UE C++ and HLSL)

• unreal-editor-mcp — Build diagnostics and editor log tools (Live Coding, error parsing, log search)

• unreal-blueprint-mcp — Blueprint graph reading (nodes, pins, connections, execution flow)

• unreal-blueprint-reader — C++ editor plugin that serializes Blueprint graphs to JSON for AI tooling

• unreal-material-mcp — Material graph intelligence, editing, and procedural creation (46 tools: expressions, parameters, instances, graph building, templates, C++ plugin)

• unreal-config-mcp — Config/INI intelligence (resolve inheritance chains, search settings, diff from defaults, explain CVars)

• unreal-animation-mcp — Animation data inspector and editor (sequences, montages, blend spaces, ABPs, skeletons, 62 tools)

• unreal-niagara-mcp — Niagara VFX intelligence and editing (emitters, modules, HLSL generation, procedural creation, 70 tools)

• unreal-api-mcp by Nico Bailon — API surface lookup (signatures, #include paths, deprecation warnings)

Together these servers give AI agents full-stack UE understanding: engine internals, API surface, your project code, build/runtime feedback, Blueprint graph data, config/INI intelligence, material graph inspection + editing, animation data inspection + editing, and Niagara VFX inspection + creation.

Quick Start

Install from GitHub

uvx --from git+https://github.com/tumourlove/unreal-project-mcp.git unreal-project-mcp --index

Claude Code Configuration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "unreal-project": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tumourlove/unreal-project-mcp.git", "unreal-project-mcp"],
      "env": {
        "UE_PROJECT_PATH": "D:/Unreal Projects/MyProject",
        "UE_PROJECT_NAME": "MyProject"
      }
    }
  }
}

Or run from local source during development:

{
  "mcpServers": {
    "unreal-project": {
      "command": "uv",
      "args": ["run", "--directory", "C:/Projects/unreal-project-mcp", "python", "-m", "unreal_project_mcp"],
      "env": {
        "UE_PROJECT_PATH": "D:/Unreal Projects/MyProject",
        "UE_PROJECT_NAME": "MyProject"
      }
    }
  }
}

The server auto-indexes on first run if no database exists.

Tools (17)

C++ Source Intelligence

Config & Build Intelligence

Runtime & Asset Intelligence

CLI

# Index project source (first time)
unreal-project-mcp --index

# Rebuild from scratch
unreal-project-mcp --reindex

# Incremental update (only changed files)
unreal-project-mcp --reindex-changed

# Run as MCP server (default, used by Claude Code)
unreal-project-mcp

Environment Variables

How It Works

1. Discovery — Walks Source/ for game modules and Plugins/*/Source/ for plugin modules. Uses the actual module subdirectory names, not plugin folder names (handles marketplace hashed folders correctly).

2. C++ Parsing — Uses tree-sitter with the C++ grammar to build ASTs. Handles UE macros (UCLASS, UFUNCTION, UPROPERTY, etc.) with regex fallback for misparsed nodes. Extracts replication specifiers, asset path references, and log category declarations.

3. Config & Build Parsing — Parses UE's non-standard INI format (duplicate keys, +/-/./! prefixes), Build.cs module dependencies, and .uplugin plugin descriptors.

4. Post-Processing — Scans for gameplay tags across C++, INI, and CSV sources. Applies pattern-based classification to identify subsystems, anim notifies, and console commands.

5. Storage — SQLite with FTS5 full-text search. 19 tables covering symbols, inheritance, cross-references, config entries, asset references, gameplay tags, replication entries, module dependencies, plugins, log categories, and pattern tags.

6. Serving — FastMCP server exposes 17 tools over stdio. Claude Code manages the server lifecycle automatically.

What Gets Indexed

C++ Source:

• Classes, structs, enums (with base classes and UE macro metadata)

• Functions (declarations and definitions, with qualified names like UMyClass::MyMethod)

• Variables (member variables with UPROPERTY detection)

• Includes, call references, type references, inheritance relationships

• Replication markers (Server/Client/NetMulticast RPCs, Replicated/ReplicatedUsing properties)

• Asset path references (TEXT("/Game/..."), LoadObject<T>, ConstructorHelpers, FSoftObjectPath)

• Log categories (DECLARE_LOG_CATEGORY_EXTERN, DEFINE_LOG_CATEGORY)

• Docstrings (/** */ and /// comments)

Config & Build:

• INI config key-value pairs across all Config/*.ini files

• Build.cs module dependencies (public, private, dynamically loaded)

• Plugin descriptors (metadata, modules, plugin dependencies)

Derived Intelligence:

• Gameplay tags from C++ source, INI config, and CSV data tables

• Data table struct detection (FTableRowBase children)

• Pattern classifications (subsystems, anim notifies, console commands)

Adding to Your Project's CLAUDE.md

## Project Intelligence (unreal-project MCP)

Use `unreal-project` MCP tools to search, read, and understand your project's C++ source,
config files, module dependencies, gameplay tags, and replication topology.

| Tool | When |
|------|------|
| `search_project` | Full-text search across project C++ source |
| `read_project_source` | Read implementation of a class/function |
| `find_project_callers` | What calls this function? |
| `find_project_references` | Find all usage sites of a symbol |
| `get_project_class_hierarchy` | Inheritance tree (ancestors/descendants) |
| `get_config_values` | Look up config/INI values by key |
| `get_module_dependencies` | Module dependency graph from Build.cs |
| `search_gameplay_tags` | Search gameplay tag definitions and usage |
| `get_replication_map` | Replicated properties and RPCs |

Development

# Clone and install
git clone https://github.com/tumourlove/unreal-project-mcp.git
cd unreal-project-mcp
uv sync

# Run tests (157 tests)
uv run pytest -v

# Run locally
UE_PROJECT_PATH="/path/to/project" uv run python -m unreal_project_mcp

Requirements

• Python 3.11+

• uv (recommended) or pip

License

MIT