unreal-source-mcp

Deep Unreal Engine source intelligence for AI development via Model Context Protocol.

Indexes all UE C++ and HLSL source code into a local SQLite database and exposes structural queries — class hierarchies, call graphs, cross-references, and full-text search across 80k+ files and 1M+ symbols — as MCP tools for AI coding assistants like Claude Code.

Why?

AI assistants hallucinate engine APIs, guess at implementation patterns, and can't see how Epic actually built things. This server gives them deep structural access to the real engine source — so they write code that matches how UE actually works, not how they imagine it works.

Complements (does not replace):

• unreal-project-mcp — Project-level source intelligence (your C++ code)

• 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.

Related MCP server: MCP Indexer

Quick Start

Install from GitHub

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

Claude Code Configuration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "unreal-source": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tumourlove/unreal-source-mcp.git", "unreal-source-mcp"],
      "env": {
        "UE_SOURCE_PATH": "C:/Path/To/UE_5.x/Engine/Source",
        "UE_SHADER_PATH": "C:/Path/To/UE_5.x/Engine/Shaders"
      }
    }
  }
}

Or run from local source during development:

{
  "mcpServers": {
    "unreal-source": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unreal-source-mcp", "python", "-m", "unreal_source_mcp"],
      "env": {
        "UE_SOURCE_PATH": "C:/Path/To/UE_5.x/Engine/Source",
        "UE_SHADER_PATH": "C:/Path/To/UE_5.x/Engine/Shaders"
      }
    }
  }
}

The server auto-indexes on first run (~10-15 min). All subsequent queries are instant.

Tools

CLI

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

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

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

Environment Variables

How It Works

1. Discovery — Walks Engine/Source/ for all Runtime, Editor, Developer, and plugin modules. Optionally indexes Engine/Shaders/ for HLSL (usf/ush).

2. Parsing — Uses tree-sitter with the C++ grammar to build ASTs. Handles UE macros (UCLASS, UFUNCTION, UPROPERTY, etc.) with regex fallback for misparsed nodes.

3. Storage — SQLite with FTS5 full-text search. 80k+ files, 1M+ symbols indexed. Database is versioned per UE version at ~/.unreal-source-mcp/ue_{version}.db.

4. Serving — FastMCP server exposes 9 tools over stdio. Claude Code manages the server lifecycle automatically.

What Gets Indexed

• All engine C++ source (Runtime, Editor, Developer, built-in plugins)

• HLSL shader source (usf/ush files)

• Classes, structs, enums with inheritance and UE macro metadata

• Functions (declarations and definitions with qualified names)

• Call references, type references, include relationships

• Docstrings and symbol context

Add to Your CLAUDE.md

## Unreal Engine Source Intelligence (unreal-source MCP)

Use `unreal-source` MCP tools to read actual engine source code, trace call graphs,
and explore class hierarchies. **Use this when you need to understand HOW something
works, not just its API signature.**

| Tool | When |
|------|------|
| `read_source` | Read the actual implementation of a class/function |
| `find_references` | Find all usage sites of a symbol |
| `find_callers` | What calls this function? |
| `find_callees` | What does this function call? |
| `search_source` | Full-text search across C++ and shader source |
| `get_class_hierarchy` | Inheritance tree (ancestors/descendants) |
| `get_module_info` | Module stats, file counts, key classes |
| `get_symbol_context` | Symbol definition with surrounding context |

**Rules:** Use `read_source` to understand engine internals before reimplementing
patterns. Use `find_callers` to see how Epic uses their own APIs.

Development

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

# Run tests
uv run pytest -v

# Run locally
UE_SOURCE_PATH="/path/to/Engine/Source" uv run python -m unreal_source_mcp

Requirements

• Python 3.11+

• uv (recommended) or pip

• A local Unreal Engine source installation

License

MIT