LSP MCP Server

lsp-mcp-server

An MCP (Model Context Protocol) server that bridges Claude Code to Language Server Protocol (LSP) servers, enabling semantic code intelligence capabilities.

Overview

lsp-mcp-server acts as a bridge between Claude Code and language servers, providing powerful code intelligence features:

• Go to Definition - Navigate to where symbols are defined
• Find References - Find all usages of a symbol across the workspace
• Hover Information - Get type information and documentation
• Code Completion - Get intelligent code suggestions
• Diagnostics - Access errors, warnings, and hints from the language server
• Symbol Search - Search for symbols in documents or across the workspace
• Rename - Safely rename symbols across the entire codebase
• Code Actions - Apply quick fixes, refactorings, and organize imports
• Call Hierarchy - See who calls a function and what it calls
• Type Hierarchy - Explore class inheritance and interface implementations
• Format Document - Format code using the language server's formatter
• Smart Search - Comprehensive symbol analysis in a single call
• File Analysis - Explore imports, exports, and file relationships

┌─────────────┐      ┌──────────────────┐      ┌───────────────────┐
│ Claude Code │────▶│  lsp-mcp-server  │────▶│ Language Servers  │
│   (MCP)     │◀────│   (this tool)    │◀────│ (TypeScript, etc) │
└─────────────┘      └──────────────────┘      └───────────────────┘
      stdio              stdio/JSON-RPC            stdio

Features

• 24 MCP Tools for comprehensive code intelligence
• 8 Languages Supported out of the box:
  • TypeScript / JavaScript
  • Python
  • Rust
  • Go
  • C / C++
  • Ruby
  • PHP
  • Elixir
• Multi-root Workspace - Proper monorepo support with per-workspace server instances
• Push-based Diagnostics - Real-time error/warning caching from language servers
• Human-friendly Positions - All line/column numbers are 1-indexed
• Safe Rename - Preview changes before applying with dry-run mode
• Automatic Server Management - Servers start on-demand and restart on crash
• Configurable - Customize language servers, timeouts, and more
• Security Features - File size limits, workspace boundary validation, absolute path enforcement

Installation

Prerequisites

• Node.js 18.0.0 or higher
• Language servers for the languages you want to use:

# TypeScript/JavaScript
npm install -g typescript-language-server typescript

# Python
pip install python-lsp-server

# Rust
rustup component add rust-analyzer

# Go
go install golang.org/x/tools/gopls@latest

# C/C++
# Ubuntu/Debian:
sudo apt install clangd
# macOS:
brew install llvm

# Ruby
gem install solargraph

# PHP
npm install -g intelephense

# Elixir
mix escript.install hex elixir_ls
# Or download pre-built releases from:
# https://github.com/elixir-lsp/elixir-ls/releases

Install lsp-mcp-server

# Clone the repository
git clone <repository-url>
cd lsp-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Verify installation
node dist/index.js --help

Global Installation (Optional)

# Link globally for easy access
npm link

# Now you can run from anywhere
lsp-mcp-server

Configuration with Claude Code

1. Add to Claude Code MCP Settings

Create or edit the .mcp.json file in your home directory:

Location: ~/.mcp.json (user-level) or .mcp.json in your project root (project-level)

{
  "mcpServers": {
    "lsp": {
      "command": "node",
      "args": ["/absolute/path/to/lsp-mcp-server/dist/index.js"],
      "env": {
        "LSP_LOG_LEVEL": "info"
      }
    }
  }
}

Or if installed globally via npm link:

{
  "mcpServers": {
    "lsp": {
      "command": "lsp-mcp-server"
    }
  }
}

2. Restart Claude Code

After updating the configuration, restart Claude Code to load the new MCP server.

3. Verify Installation

In Claude Code, ask:

"Use lsp_server_status to check available language servers"

You should see a response showing the server is running.

4. Enforce LSP Tool Usage (Recommended)

To make Claude Code consistently prefer LSP tools over alternatives like Grep and Glob for code navigation, add instructions to your global ~/.claude/CLAUDE.md file:

## LSP Server - REQUIRED FIRST STEP

**BEFORE any code analysis, navigation, or codebase exploration, you MUST:**

1. Run `lsp_server_status` to check running servers
2. If the relevant language server is NOT running → run `lsp_start_server` immediately
3. ONLY AFTER the LSP server is running, proceed with analysis

This is a hard requirement, not a preference. Do NOT skip this step.

## LSP Tool Requirements

When LSP MCP tools are available, you MUST use them instead of alternatives:

| Task | REQUIRED Tool | FORBIDDEN Alternatives |
|------|---------------|----------------------|
| Find w