lsp-mcp-server

A lightweight MCP server that exposes type-aware code navigation and fast file search to AI agents via language servers. It manages language server processes on demand, routes LSP requests from MCP tool calls, and returns structured results — letting agents jump to definitions, find references, list symbols, and locate files without reading entire codebases.

Installation

Option 1: Claude Code Plugin (recommended)

One command to clone, install, and register as a Claude Code plugin:

git clone https://github.com/garretpremo/lsp-mcp-server.git ~/.local/share/lsp-mcp-server \
  && cd ~/.local/share/lsp-mcp-server && bun install \
  && bash scripts/install-plugin.sh

Restart Claude Code (or run /reload-plugins) to activate. The plugin adds a skill that guides Claude on when to use each tool, plus the MCP server runs automatically for each project.

Option 2: Per-session (no install)

git clone https://github.com/garretpremo/lsp-mcp-server.git ~/tools/lsp-mcp-server \
  && cd ~/tools/lsp-mcp-server && bun install

Then start Claude Code with:

claude --plugin-dir ~/tools/lsp-mcp-server/plugin

Option 3: Manual MCP config

Add to your project's .mcp.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "lsp-mcp-server": {
      "command": "bun",
      "args": ["run", "/path/to/lsp-mcp-server/src/index.ts", "--project", "."]
    }
  }
}

Option 4: Standalone (any MCP client)

bun run src/index.ts --project /path/to/your/project

Communicates via stdio JSON-RPC — works with any MCP-compatible client.

Available Tools

Tool	Description
find_file	Fuzzy file name search against the project file index
reindex	Rebuild the file index (full project or a subdirectory)
go_to_definition	Jump to the definition of a symbol at a given file position
find_references	Find all references to a symbol at a given file position
document_symbols	List all symbols (classes, functions, etc.) in a file
workspace_symbol	Search for symbols by name across the entire project

All LSP navigation tools accept optional enrichment flags: includeKind, includeContainer, and includeDocstring.

Configuration

Place a config.json in your project root to override language server commands or the request timeout:

{
  "requestTimeout": 15000,
  "languageServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "java": {
      "command": "jdtls",
      "args": []
    }
  }
}

If no config.json is found, defaults are used. requestTimeout is in milliseconds (default: 10000).

Benchmarks: lsp-mcp-server vs JetBrains MCP

Tested against a 4,381-file Angular/TypeScript project (Nx monorepo).

File Search — "document-viewer"

	lsp-mcp-server	JetBrains MCP
Response size	~1,500 chars	9,792 chars
Results	10 files, ranked by relevance	40 items (files + dirs), unranked, duplicated by worktrees
Format	Absolute + relative paths	Flat path list with worktree duplicates

Document Symbols — reports.service.ts

	lsp-mcp-server	JetBrains MCP
Response size	~5,200 chars	4,486 chars
Result type	31 structured symbols (name, kind, container, snippet)	Raw file text (no symbols tool available)
Structured	Yes — class, method, property with hierarchy	No — LLM must parse symbols from raw text

Go To Definition — HttpClient import

	lsp-mcp-server	JetBrains MCP
Response size	~550 chars	34,868 chars
Result type	1 precise definition location	50 text matches (grep-style, not semantic)
Semantic	Yes — LSP-powered, type-aware	No — text search with search_in_files_by_text

Agent Token Usage (identical tasks, Sonnet model)

	lsp-mcp-server	JetBrains MCP
Total tokens	18,910	25,994
Tool calls	3	10

Summary

• 6.5x smaller file search responses
• 63x smaller definition lookup responses
• 27% fewer tokens consumed by the agent
• Structured symbol data vs raw text
• True LSP semantics vs text-based grep

Prerequisites

The following language servers must be installed and available on your PATH:

• TypeScript / JavaScript: typescript-language-server

  npm install -g typescript-language-server typescript
  

• Java: jdtls (Eclipse JDT Language Server)

Language servers are started lazily — only when a file of the matching type is first accessed.

License

MIT