Locus MCP server

Locus

Locus gives your AI coding agent a map of your codebase. Whether you write code yourself or work through Cursor, Codex, or Claude Code, Locus connects your agent to the same go-to-definition and find-references intelligence your IDE uses — through MCP (Model Context Protocol), a standard plug-in layer for AI tools. Configure it once; your agent uses six small tools to find symbols, trace callers, read types, and catch errors before you run tests.

Why you might want this

• Find the real definition — Your agent can locate UserService.authenticate even when it is re-exported, overloaded, or buried in a large file — not just wherever the name appears as text.
• See who calls what — Before a refactor, list every reference to a function or class so nothing breaks silently.
• Read types and docs — Ask what a variable or parameter actually is, without guessing from variable names.
• Catch errors early — Surface compiler and linter problems right after an edit, instead of waiting for a full test run.

Who this is for

Locus is for AI-first builders: developers, indie hackers, and PMs who work through an agent and want it to understand code structure, not just search strings.

It fits when your agent already edits files well (Cursor's Edit tool, Claude Code, Codex) and you want to add semantic navigation on top — without turning your setup into a second IDE inside MCP.

It is not for people who want symbolic editing, agent memory, or a full refactoring toolkit inside MCP. For that, look at Serena — a broader option that does more inside the protocol. Locus stays intentionally small: six tools, npx install, complements your host.

Get started in 5 minutes

1. Install a language server (if you do not have one yet) — for TypeScript/JavaScript: npm install -g typescript-language-server typescript. See Installing language servers for Python, Go, and Rust.
2. Run one-time setup in your project folder:

npx @paladini/locus-mcp init
   npx @paladini/locus-mcp check

1. Add Locus to your agent's MCP config — MCP is how AI hosts call helper tools like Locus; copy a block from Copy-paste configs below and set cwd to your project's absolute path.
2. Reload MCP — restart Cursor, reload Codex, or reopen Claude Code so the new server appears.
3. Try a prompt — ask your agent: "Use Locus to find where UserService is defined and list all references." If it calls the locate and refs tools, you are set.

Requirements: Node.js 22+. Language servers on your PATH for the languages you use.

Copy-paste configs

Your agent host spawns Locus automatically — you never run serve by hand during normal use.

Cursor

Create or edit .cursor/mcp.json in your project (or global Cursor MCP settings):

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Codex

Add to ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/absolute/path/to/your/project"

For a project-scoped config, you can use cwd = "." instead.

Shortened. The full README is on GitHub.