lexis-mcp

A code-search MCP server that gives AI coding assistants 28+ specialized tools to navigate large codebases — without burning tokens.

Result: ~80% fewer tokens per complex task (measured on real bug investigations in a 500k-line PHP codebase: ~15,000 tokens → ~3,000).

Status: Validated on Claude Code (the only client tested in real workflows so far). Should work with any standard MCP client (Cursor, Windsurf, Continue, Cline, Zed, etc.) but those are untested. Issues and contributions welcome.

No vectors. No embeddings. No external services. Just ripgrep + AST symbol extraction + smart ranking.

Install

npm install -g lexis-mcp

That's it. The postinstall:

• Registers Lexis with Claude Code automatically (user scope, works in any project)
• Writes usage hints to ~/.claude/CLAUDE.md so Claude prefers Lexis over Read/Grep
• Bundles ripgrep — no extra dependencies

For other clients (Cursor, Windsurf, OpenCode, etc.):

lexis setup --global --client cursor      # prints the JSON to paste into your client config
lexis setup --global --all                # prints config for all 10 supported clients

Why it exists

LLMs are smart but not omniscient. When you ask Claude Code about a bug in a 100k-line codebase, it has two options:

1. Read whole files blindly — burns tokens, often misses the cause
2. Use search tools — fast and precise, but only if those tools exist

lexis-mcp provides those tools. Claude Code calls them autonomously through MCP, gets exactly what it needs, and answers with a fraction of the context.

Example: how a session looks

You (in Claude Code, after npm install -g lexis-mcp):

"There's a bug — config files aren't being regenerated after updating the database records. The fix is somewhere around ServiceClient::reloadCache."

What Claude does internally (visible as tool calls in your session):

1. mcp__lexis__notes(query="reloadCache")
   → Recovers prior findings on this branch (none yet, first session)

2. mcp__lexis__search_code(query="reloadCache", context="bug")
   → Returns 3 ranked results in ./src and ./scripts/
   (~150 tokens vs 2,500 if Claude had read the files)

3. mcp__lexis__get_symbol(name="reloadCache")
   → Returns just the function body (~120 tokens, no surrounding boilerplate)

4. mcp__lexis__call_chain(symbol="reloadCache", direction="upstream")
   → Identifies the lifecycle hook that triggers it

5. mcp__lexis__find_writes(target="config/runtime.cfg")
   → Returns: a deploy-time script that writes the file
   → "config is written at deploy, not at runtime"

6. Claude reasons → root cause found

What Claude tells you:

The branch name suggests it fixes the config issue, but reloadCache() only reloads the in-memory cache via RPC — it does NOT regenerate the config file. The config is written by a deploy-time script, not at runtime. Two distinct mechanisms.

Then Claude saves the finding:

mcp__lexis__note(
  content="reloadCache() only reloads in-memory state, not the on-disk config.
           Config is written by deploy script, no runtime regeneration path exists.",
  tags=["bug", "root-cause"],
  files=["src/.../ServiceClient.php", "scripts/deploy/config-writer"]
)

Six months later you reopen the branch — Claude reads that note immediately on session start. Zero re-investigation.

Token totals for this session: ~2,800 tokens with Lexis vs ~14,000 if Claude had read those files directly.

(Numbers measured on a real ~500k LOC PHP/telecom codebase. Names anonymized.)

Supported clients

Honest status: Lexis is validated on Claude Code (real bug-fix and feature sessions in production projects). The other clients listed below should work because Lexis implements the standard MCP protocol — but they have not been tested by us yet. If you use one and it works (or breaks), please open an issue.

| Client | Auto-register on i

... View full README on GitHub