Swift Index Store Mcp

IndexStoreMCP

An MCP server that gives AI agents semantic code navigation for Xcode projects. Instead of relying on grep and file reading, agents can look up symbols by name, find definitions and references by USR, trace protocol conformances and overrides, and get structural outlines of files — the same navigation that Xcode provides via Cmd+Click and Find Usages.

Built on Apple's IndexStoreDB library, which reads the index data that Xcode generates during builds.

When is this useful?

• Large codebases where grep returns too much noise. Symbol lookup by USR is exact — no false matches from comments, strings, or similarly named symbols.
• Refactoring — find all protocol conformances, method overrides, and extensions before changing a type or interface. relatedOccurrences answers "what will break?" in one call.
• Navigating unfamiliar code — agents can trace call graphs and jump between definitions and references the same way a developer uses Cmd+Click in Xcode, instead of guessing at file structure.
• Reducing context window usage — symbolsInFile returns a structural outline (names, kinds, line numbers) without reading the entire source file. For large files this keeps the agent's context focused.
• Cross-dependency navigation — the index includes symbols from your project's Swift package dependencies, not just your own source files.

For small projects, grep and file reading are usually fast enough. This MCP pays off as project size and complexity grow.

Prerequisites

• macOS 14+
• Xcode installed (provides libIndexStore.dylib)
• The target project must have been built in Xcode at least once so the index store exists in DerivedData

Setup

Build

git clone https://github.com/hpatel-lincoln/swift-index-store-mcp.git
cd swift-index-store-mcp
swift build -c release

The binary is at .build/release/IndexStoreMCP inside the cloned directory.

Configure your MCP client

Claude Code

claude mcp add index-store-mcp /path/to/swift-index-store-mcp/.build/release/IndexStoreMCP

Claude Desktop / Cursor / other MCP clients

Add to your MCP configuration file:

{
  "mcpServers": {
    "index-store-mcp": {
      "command": "/path/to/swift-index-store-mcp/.build/release/IndexStoreMCP"
    }
  }
}

Configuring your agent

Adding the MCP server makes the tools available, but agents will often default to grep unless instructed otherwise. Add the following to your project's CLAUDE.md (or equivalent agent instructions file) to encourage the agent to use the index:

## Xcode Navigation (index-store-mcp)

This project has the index-store-mcp server configured. Use it for code navigation
instead of grep when working with Swift/Objective-C source files.

### When to use
- Finding where a symbol is defined, referenced, or called
- Tracing protocol conformances, method overrides, or extensions
- Getting a structural outline of a file before reading it
- Disambiguating symbols with common names (e.g., init, configure, handle)
- Identifying a symbol's type or kind (class, protocol, enum, method, property)
- Navigating into symbols defined in package dependencies

### Workflow
1. Call `loadIndex` with the workspace/project path once at the start of a session
2. Use `searchSymbol` (exact name, preferred) or `searchSymbolPattern` (fuzzy/partial,
   use longer patterns to reduce noise) to find USRs
3. Use `getOccurrences` or `relatedOccurrences` with a USR to find all usage sites
4. Use `symbolAtPosition` when you're reading a file and need the USR at a specific position
5. Use `symbolsInFile` to get a file's structure without reading the full source
6. Call `refreshIndex` after a build to pick up changes

Tools (invoked by the agent)

loadIndex

Must be called first. Loads the Xcode index for a project.

workspacePath: "/path/to/MyApp.xcworkspace"

Accepts .xcworkspace, .xcodeproj, or a bare directory (for Swift packages opened in Xcode).

searchSymbol

Looks up a symbol by its exact name as it appears in source code. Returns one or more USRs (Unified Symbol Resolutions) that uniquely identify the symbol.

name: "viewDidLoad"

searchSymbolPattern

Fuzzy search when you only know a partial name. Supports subsequence matching — mvc finds MyViewController, vdl finds viewDidLoad.

pattern: "mvc"

symbolAtPosition

Returns the symbol at a specific file location. More precise than searchSymbol when the name is ambiguous (e.g., init).

file: "/path/to/MyFile.swift", line: 42, column: 10

getOccurrences

Given a USR, returns every location where that symbol is defined, referenced, or called. Supports role filtering (definition, reference, call, etc.).

usr: "s:13MyApp0A14ViewControllerC"

relatedOccurrences

Finds structural relationships: protocol conformances, method overrides, type extensions. Essential before refactoring a protocol or base class.

usr: "s:13MyApp0A8ProtocolP"

symbolsInFile

Returns a structural outline of all symbols defined in a file — names, kinds, USRs, and line numbers.

file: "/path/to/MyFile.swift"

refreshIndex

Polls for index changes after a build. Call this when query results may be stale.

Typical agent workflow

loadIndex(workspacePath: "/path/to/MyApp.xcworkspace")
  → "Index loaded"

searchSymbol(name: "AppDelegate")
  → [{ usr: "s:5MyApp0A8DelegateC", kind: "class", location: "AppDelegate.swift:3" }]

getOccurrences(usr: "s:5MyApp0A8DelegateC", roles: ["reference"])
  → [{ file: "main.swift", line: 12, role: "reference" }, ...]

symbolsInFile(file: "/path/to/AppDelegate.swift")
  → [{ name: "AppDelegate", kind: "class", line: 3 },
     { name: "application(_:didFinishLaunchingWithOptions:)", kind: "instanceMethod", line: 5 }, ...]

How it works

When Xcode builds a project, the compiler writes symbol index data to DerivedData/Index.noindex/DataStore. IndexStoreMCP reads this data through IndexStoreDB and exposes it over the Model Context Protocol via stdio transport.

The server discovers DerivedData automatically by checking:

1. Custom DerivedData location from Xcode preferences
2. A DerivedData folder next to the workspace (relative mode)
3. The default ~/Library/Developer/Xcode/DerivedData

System framework symbols (UIKit, Foundation, etc.) are filtered out by default. Pass includeSystem: true to any tool to include them.

Testing

See [TESTING.md](TESTING.md).

License

IndexStoreMCP is released under the MIT License. See [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hpatel-lincoln
• Source: hpatel-lincoln/swift-index-store-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.