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

Tool	Description
search_project	Full-text search across project C++ source. Supports FTS, regex, and substring modes. Filter by module, path, or symbol kind.
read_project_source	Read the actual implementation of a class, function, or struct with line numbers. Shows both .h and .cpp.
find_project_callers	Find all functions that call a given function. Includes heuristic delegate/binding detection.
find_project_callees	Find all functions called by a given function.
find_project_references	Find all usage sites of a symbol (calls, type references, includes).
get_project_class_hierarchy	Show the inheritance tree for a class — ancestors, descendants, or both.
get_project_module_info	Module statistics: file count, symbol counts by kind, key classes.

Config & Build Intelligence

Tool	Description
get_config_values	Look up config/INI values by key with optional section filter. Cross-references with UPROPERTY(Config) C++ symbols.
search_config	Full-text search across all project config/INI files (sections, keys, values).
get_module_dependencies	Build.cs module dependency graph — dependencies, dependents, or both directions.
get_plugin_info	Plugin metadata, modules, and plugin-to-plugin dependencies from .uplugin files.
find_data_table_schema	Data table struct definitions — finds FTableRowBase children and linked data tables.

Runtime & Asset Intelligence

Tool	Description
find_asset_references	Find C++ code that references assets by path (TEXT("/Game/..."), LoadObject, ConstructorHelpers, FSoftObjectPath).
search_gameplay_tags	Search gameplay tag definitions and usage across C++, INI config, and CSV data tables.
find_log_sites	Find log category declarations (DECLARE_LOG_CATEGORY_EXTERN) and UE_LOG usage sites.
get_replication_map	Replicated properties and Server/Client/NetMulticast RPCs for a class or the entire project.
search_project_tags	Pattern-based classifications: subsystems, anim notifies, console commands.

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

Variable	Required	Description
UE_PROJECT_PATH	Yes	Path to the project root (containing Source/ and Plugins/)
UE_PROJECT_NAME	No	Project name for the DB filename. Auto-detected from .uproject if not set.
UNREAL_PROJECT_MCP_DB_DIR	No	Override DB storage location (default: ~/.unreal-project-mcp/)

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