Universal LSP MCP Server
One MCP server to rule all Language Servers — automatic language detection, zero-config setup.
Overview
A Model Context Protocol (MCP) server that gives language models access to Language Server Protocol (LSP) functionality across all major programming languages. Unlike existing LSP-MCP servers, this project supports 13 languages out of the box with zero manual configuration — it automatically detects your codebase, selects the right language server, and exposes all LSP operations through a stable, language-independent tool interface.
Supported Languages
| Language | Language Server | Auto-Detected Via |
|---|
| Python | pyright / pylsp | pyproject.toml, setup.py |
| TypeScript | typescript-language-server | tsconfig.json |
| JavaScript | typescript-language-server | package.json |
| C# | omnisharp | *.csproj, *.sln |
| Java | vscode-java / jdtls | pom.xml, build.gradle |
| Go | gopls | go.mod |
| Rust | rust-analyzer | Cargo.toml |
| C / C++ | clangd | *.c, *.cpp, *.h |
| Ruby | solargraph | Gemfile |
| PHP | intelephense | composer.json |
| Kotlin | kotlin-language-server | build.gradle.kts |
| Swift | sourcekit-lsp | Package.swift |
Features
- 🔍 Automatic Language Detection — Scans project root for language markers (
package.json, Cargo.toml, go.mod, etc.)
- 🔄 Auto Language Server Selection — Hardcoded mapping with fallback servers; installs missing LSPs automatically
- 🤖 Hands-Free Initialization — Clients that support MCP Roots auto-initialize on connect —
lsp_init disappears from the tool list once all servers start cleanly
- 💾 Cross-Session Persistence — Initialized workspaces and their ready languages are remembered across server restarts
- 🔁 Graceful Degradation —
lsp_init reappears if a previously-working server starts failing (e.g. language added, binary missing)
- 🛠 12 LSP Tools — Definition, references, symbols, diagnostics, rename, code actions, formatting, and more
- 📝 Read & Write Operations — Both inspection and modification of code via LSP
- 🌐 Polyglot Support — Multiple language servers run simultaneously in the same project
- 📋 Hybrid Responses — Human-readable
text field + raw LSP data in raw field
- 🔌 MCP Stdio Protocol — Works with any MCP-compatible client
- ⚡ Zero Config — Install and run, no per-language setup required
Installation
Important: Install lsp-mcp on the same machine where your code lives. The language servers it manages need direct filesystem access to your codebase — they cannot work over a remote connection or on a different machine than your source files.
npm install -g @theupsider/lsp-mcp@latest
bun install -g @theupsider/lsp-mcp@latest
Quickstart
VS Code / Cursor
Add to your workspace .vscode/mcp.json (recommended — ensures the server runs on the same machine as your code, including SSH remotes, WSL, and Dev Containers):
{
"servers": {
"lsp-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@theupsider/lsp-mcp@latest"]
}
}
}
Why workspace config? VS Code runs servers defined in .vscode/mcp.json wherever the workspace lives. Servers defined in your user profile always run locally — which breaks LSP when your code is on a remote machine.
CLI
The server starts with no active project. Most clients auto-initialize when they support the MCP Roots protocol (VS Code, Copilot, etc.), but lsp_init remains available as a manual override.
For clients without Roots support, the first action the model must take is calling lsp_init:
lsp_init({ root: "/path/to/your/project" })
lsp_init will:
- Scan the root for language markers and start matching language servers (best-effort)
- Disappear from the tool list when you called it explicitly — subsequent calls to any LSP tool trigger lazy server startup for that file's language if no server was detected at init time
- Return health status for all servers that were started eagerly
Optional: pre-warm specific languages (skips detection, faster cold start):
lsp_init({ root: "/path/to/project", languages: ["python", "typescript"] })
Persistence: Once initialized, the workspace configuration (detected languages) is saved to your OS-standard config directory (~/.config/lsp-mcp/ on Linux, ~/Library/Application Support/lsp-mcp/ on macOS, %APPDATA%\lsp-mcp\ on Windows). On subsequent server startups, the MCP server will automatically reconnect using the last-known root, so you rarely need to call lsp_init again.
Re-emergence: If a language server that was previously healthy fails to start (e.g. you added a new language or removed a binary), lsp_init will reappear in the tool list, signaling the model should re-initialize.
| Tool | Description | Key Parameters | Visibility |
|---|
lsp_init | Initialize server for a project root | root (required), languages (optional string array) | Conditional — hidden after a successful explicit lsp_init call |
lsp_definition | Go to definition | file, line, character | Always |
lsp_references | Find all references | file, line, character | Always |
lsp_document_symbols | List symbols in a file | file | Always |
lsp_workspace_symbols | Search symbols across workspace | query (limit: 100–500 results) | Always |
lsp_diagnostics | Get errors & warnings | file (scope: file or workspace) | Always |
lsp_type_definition | Go to type definition | file, line, character | Always |
lsp_implementation | Find implementations | file, line, character | Always |
lsp_health | Check status of all LSP servers | (none) | Always |
| Tool | Description | Key Parameters |
|---|
lsp_rename | Rename symbol | file, line, character, newName |
lsp_code_action | Apply / list code actions | file, line, character, apply |
lsp_formatting | Format document | file |
lsp_range_formatting | Format code range | file, range |
Configuration
| Environment Variable | Description | Default |
|---|
LSP_MCP_LOG_LEVEL | Log level: error, info, debug | info |
Setup Scripts
Two helper scripts are included for setting up a development environment:
setup-languages-ubuntu24.sh — Installs all language runtimes, compilers, and toolchains on Ubuntu 24.04 (Python, Node.js, Java, Go, Rust, Ruby, PHP, Kotlin, Swift, etc.)setup-lsp.sh — Installs all language servers (pyright, typescript-language-server, omnisharp, jdtls, gopls, rust-analyzer, clangd, solargraph, intelephense, kotlin-language-server)
chmod +x setup-languages-ubuntu24.sh
./setup-languages-ubuntu24.sh
chmod +x setup-lsp.sh
./setup-lsp.sh
source ~/.bashrc
Troubleshooting
Language server not found
If a language server cannot be auto-installed, the server logs a structured error and continues running for other languages. Manually install the missing server:
pipx install python-lsp-server
dotnet tool install -g omnisharp-roslyn
npm install -g vscode-java
gem install solargraph
Server not detecting language
Ensure your project root contains a language marker file (e.g., package.json for TypeScript, Cargo.toml for Rust). The server scans the directory passed to lsp_init for these markers.
High memory usage
Each language server runs as a separate process. For large projects with many languages, consider limiting the workspace or using LSP_MCP_LOG_LEVEL=info to monitor server health.
Architecture
┌─────────────────────────────────────────────┐
│ MCP Client (AI Model) │
└──────────────────┬──────────────────────────┘
│ MCP Protocol (stdio)
▼
┌─────────────────────────────────────────────┐
│ LSP MCP Server (Node.js) │
│ ┌───────────┐ ┌──────────┐ ┌───────────┐ │
│ │ lsp_init │ │ lsp_... │ │ lsp_... │ │
│ └─────┬─────┘ └────┬─────┘ └─────┬─────┘ │
│ └─────────────┼─────────────┘ │
│ ▼ │
│ Language Router & Adapter │
│ (auto-detects language → selects LSP) │
└──────┬──────────┬──────────┬───────────┬─────┘
│ │ │ │
▼ ▼ ▼ ▼
pyright typescript gopls clangd
pylsp lsp rust- ...
analyzer
License
Apache-2.0