lsp-mcp

Bridge any Language Server to AI agents via MCP — semantic code intelligence for Claude, Cursor, and more.

Instead of building a bespoke MCP server for every language, lsp-mcp bridges the Language Server Protocol (LSP) — already implemented for hundreds of languages — to the Model Context Protocol (MCP).

Why

AI agents currently treat source code as plain text. Language servers already know the semantics: types, definitions, call graphs, errors. lsp-mcp gives agents that knowledge with ~50–200 token responses instead of dumping entire files.

One bridge. Every language. Zero duplication.

Install

cargo install lsp-mcp

Or build from source:

git clone https://github.com/quintenkasteel/lsp-mcp
cd lsp-mcp
cargo build --release
# binary at: target/release/lsp-mcp

Pre-built binaries for Linux, macOS (Intel + Apple Silicon), and Windows are attached to each GitHub Release.

Quick Start

1. Generate a config for your project:

lsp-mcp init

This auto-detects installed language servers and writes lsp-mcp.toml to the current directory. Alternatively, copy the example config and edit it:

cp lsp-mcp.example.toml lsp-mcp.toml

2. (Optional) Validate your config:

lsp-mcp check

3. Add to your MCP client config (~/.claude/settings.json for Claude Code):

{
  "mcpServers": {
    "lsp": {
      "command": "lsp-mcp",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

4. Ask Claude to use the tools:

"What is the type of process_user at line 42 of src/api.rs?" "Show me all callers of the authenticate function." "Are there any errors in src/main.rs?"

Tools

14 tools covering the full LSP feature surface:

Tool	Input	Description
hover	file, line, col	Type info and documentation for a symbol
definition	file, line, col	Where a symbol is defined
references	file, line, col	All usages of a symbol across the workspace
type_definition	file, line, col	Jump to the type definition of a symbol
implementation	file, line, col	Implementations of an interface or trait
diagnostics	file	Compiler errors and warnings for a file
document_symbols	file	All symbols (functions, types, constants) in a file
workspace_symbols	query, file	Search symbols by name across the project
signature_help	file, line, col	Function signature and parameter docs at a call site
rename	file, line, col, new_name	Preview all changes from renaming a symbol
format_document	file	Format a file using the language server's formatter
code_actions	file, line, col	Available quick fixes and refactorings at a position
call_hierarchy	file, line, col	Who calls this function (incoming) or what it calls (outgoing)
execute_command	file, command	Execute a code action or workspace command

All positional tools take file (path), line (1-indexed), col (1-indexed).

Subcommands

lsp-mcp [OPTIONS] [COMMAND]

Subcommand	Description
serve (default)	Start the MCP server over stdio
init	Auto-detect installed language servers and write lsp-mcp.toml
check	Validate config and verify all server binaries exist

lsp-mcp init

lsp-mcp init                    # write lsp-mcp.toml in current directory
lsp-mcp init --force            # overwrite existing config
lsp-mcp init --output /path/to/lsp-mcp.toml

Scans $PATH for known LSP server binaries and generates a ready-to-use config. Deduplicates overlapping language servers (e.g. if both pyright and pylsp are installed, prefers pyright).

lsp-mcp check

lsp-mcp check
lsp-mcp check --config /path/to/lsp-mcp.toml

Validates the TOML config structure and confirms each command binary is present in $PATH. Exits non-zero on any failure — useful in CI or setup scripts.

lsp-mcp serve

lsp-mcp serve
lsp-mcp --workspace /path/to/project
lsp-mcp --config /path/to/lsp-mcp.toml --workspace /path/to/project

Starts the MCP server over stdio. This is the default when no subcommand is given.

Config Reference

[[servers]]
name         = "rust"                    # Unique name (used in logs)
command      = ["rust-analyzer"]         # Binary + args; must speak LSP over stdio
extensions   = [".rs"]                   # File extensions routed to this server
root_markers = ["Cargo.toml"]           # Workspace root detection markers
language_id  = "rust"                   # Override LSP languageId (inferred if omitted)

Multiple [[servers]] blocks are allowed — one per language server. The file argument passed to each tool selects the server by matching file extension.

Supported Languages

lsp-mcp init auto-detects the following language servers:

Language	Server	Extensions
Rust	rust-analyzer	.rs
TypeScript / JavaScript	typescript-language-server	.ts, .tsx, .js, .jsx
Python	pyright-langserver	.py, .pyw
Python (alt)	pylsp	.py, .pyw
Haskell	haskell-language-server-wrapper	.hs, .lhs
Go	gopls	.go
C / C++	clangd	.c, .h, .cpp, .cc, .cxx, .hpp
Zig	zls	.zig
Lua	lua-language-server	.lua
Ruby	ruby-lsp	.rb
Elm	elm-language-server	.elm
OCaml	ocamllsp	.ml, .mli
Elixir	elixir-ls	.ex, .exs
Canopy	canopy-lsp	.can

Any LSP server that speaks JSON-RPC over stdio works — add it manually to lsp-mcp.toml even if it is not in the auto-detect list.

How It Works

Claude / MCP client
      │  JSON-RPC (stdio, newline-delimited)
      ▼
  lsp-mcp
      │  JSON-RPC (stdio, Content-Length framed)
      ▼
  rust-analyzer / pyright / gopls / ...

lsp-mcp maintains a persistent LSP session per language server. When a tool is called, it syncs the file to the server (full-text, only on change), sends the LSP request, and formats the response into compact, LLM-optimised text.

Key implementation properties:

• Resilient: crashed or slow language servers are restarted automatically
• Efficient: file content is hashed; unchanged files are not re-sent
• Safe: all file arguments are validated to be within the workspace root
• Low-overhead: connection pool shares servers across concurrent tool calls

Logging

Set LSP_MCP_LOG=debug to see all LSP traffic:

LSP_MCP_LOG=debug lsp-mcp

Logs go to stderr; stdout is reserved for MCP JSON-RPC.

Contributing

See CONTRIBUTING.md for build instructions, how to run tests, and how to add new language server support.

License

MIT OR Apache-2.0