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

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

Features

• 19 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

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_MCP_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.

Available Tools

Navigation Tools

lsp_goto_definition

Navigate to the definition of a symbol.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - definitions: Array of locations with path, line, column, and context

Example prompt: "Go to the definition of the function at line 42, column 10 in /project/src/utils.ts"

lsp_goto_type_definition

Navigate to the type definition of a symbol (useful for finding the interface/class that defines a variable's type).

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - definitions: Array of type definition locations

Example prompt: "Find the type definition for the variable at line 15, column 5 in /project/src/app.ts"

Reference Tools

lsp_find_references

Find all references to a symbol across the workspace.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - include_declaration: Whether to include the declaration (default: true)
  - limit: Maximum results (default: 100, max: 500)
  - offset: Skip results for pagination (default: 0)

Output:
  - references: Array of locations
  - total_count: Total number of references found
  - has_more: Whether there are more results

Example prompt: "Find all references to the 'UserService' class in /project/src/services/user.ts at line 5"

lsp_find_implementations

Find all implementations of an interface or abstract method.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - limit: Maximum results (default: 50, max: 100)

Output:
  - implementations: Array of implementation locations
  - total_count: Total implementations found
  - has_more: Whether there are more results

Example prompt: "Find all implementations of the interface at line 10 in /project/src/types.ts"

Information Tools

lsp_hover

Get hover information (type info, documentation) for a symbol.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - contents: Markdown-formatted type information and documentation
  - range: The range of the hovered symbol (optional)

Example prompt: "What is the type of the variable at line 25, column 8 in /project/src/main.ts?"

lsp_signature_help

Get function/method signature information when inside a call expression.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - signatures: Array of function signatures with parameters
  - active_signature: Index of the active signature
  - active_parameter: Index of the active parameter

Example prompt: "What are the parameters for the function call at line 30 in /project/src/api.ts?"

Symbol Tools

lsp_document_symbols

Get all symbols (functions, classes, variables, etc.) defined in a document.

Input:
  - file_path: Absolute path to the source file

Output:
  - symbols: Hierarchical array of symbols with name, kind, range, and children

Example prompt: "List all symbols in /project/src/components/Button.tsx"

lsp_workspace_symbols

Search for symbols across the entire workspace by name.

Input:
  - query: Search query (supports fuzzy matching)
  - kinds: Filter by symbol kinds (optional): Class, Function, Interface, Variable, etc.
  - limit: Maximum results (default: 50, max: 100)

Output:
  - symbols: Array of matching symbols with path and location
  - total_count: Total matches found
  - has_more: Whether there are more results

Example prompt: "Search for all classes containing 'Service' in the workspace"

Diagnostic Tools

lsp_diagnostics

Get cached diagnostics (errors, warnings) for a file.

Input:
  - file_path: Absolute path to the source file
  - severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')

Output:
  - diagnostics: Array of diagnostics with range, severity, message, and code
  - summary: Count of errors, warnings, info, and hints
  - note: Information about diagnostic caching

Example prompt: "Show me all errors in /project/src/index.ts"

Completion Tools

lsp_completions

Get code completion suggestions at a position.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - limit: Maximum suggestions (default: 20, max: 50)

Output:
  - completions: Array of completion items with label, kind, detail, and documentation
  - is_incomplete: Whether the list is incomplete

Example prompt: "What completions are available at line 15, column 10 in /project/src/app.ts?"

Refactoring Tools

lsp_rename

Rename a symbol across the workspace.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - new_name: The new name for the symbol
  - dry_run: Preview changes without applying (default: true)

Output:
  - changes: Map of file paths to arrays of edits
  - files_affected: Number of files that would be modified
  - edits_count: Total number of edits
  - applied: Whether changes were applied
  - original_name: The original symbol name (if available)

Example prompt: "Rename the function 'getUserData' to 'fetchUserData' at line 20 in /project/src/api.ts (dry run first)"

lsp_code_actions

Get available code actions (refactorings, quick fixes) at a position or range.

Input:
  - file_path: Absolute path to the source file
  - line: Start line number (1-indexed)
  - column: Start column number (1-indexed)
  - end_line: End line number (optional, defaults to start line)
  - end_column: End column number (optional, defaults to start column)
  - kinds: Filter by action kinds (optional): quickfix, refactor, refactor.extract, refactor.inline, source.organizeImports, etc.
  - apply: Apply the action (default: false)
  - action_index: Index of action to apply (default: 0)

Output:
  - actions: Array of available code actions with title, kind, and edits
  - applied: Whether an action was applied

Example prompt: "What refactoring options are available for the function at line 50 in /project/src/utils.ts?"

lsp_format_document

Format a document using the language server's formatting capabilities.

Input:
  - file_path: Absolute path to the source file
  - tab_size: Spaces per tab (default: 2)
  - insert_spaces: Use spaces instead of tabs (default: true)
  - apply: Apply formatting to file (default: false)

Output:
  - edits: Array of formatting edits with range and new_text
  - edits_count: Number of edits
  - applied: Whether edits were applied

Example prompt: "Format /project/src/messy-file.ts using the language server"

Hierarchy Tools

lsp_call_hierarchy

Get the call hierarchy for a function - who calls it and what it calls.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - direction: 'incoming' (callers), 'outgoing' (callees), or 'both' (default: 'both')

Output:
  - item: The call hierarchy item at the position
  - incoming_calls: Array of functions that call this function
  - outgoing_calls: Array of functions this function calls

Example prompt: "Show me all functions that call handleRequest at line 100 in /project/src/server.ts"

lsp_type_hierarchy

Get the type hierarchy for a class or interface - supertypes and subtypes.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - direction: 'supertypes' (parents), 'subtypes' (children), or 'both' (default: 'both')

Output:
  - item: The type hierarchy item at the position
  - supertypes: Array of parent types/interfaces
  - subtypes: Array of child types/implementations

Example prompt: "What classes implement the Repository interface at line 5 in /project/src/types.ts?"

Combined Tools

lsp_smart_search

Comprehensive symbol search combining multiple LSP operations in one call.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - include: Array of what to include: 'hover', 'definition', 'references', 'implementations', 'incoming_calls', 'outgoing_calls' (default: ['hover', 'definition', 'references'])
  - references_limit: Maximum references to return (default: 20)

Output:
  - symbol_name: Name of the symbol
  - hover: Type information and documentation
  - definition: Where the symbol is defined
  - references: All usages of the symbol
  - implementations: Implementations (for interfaces)
  - incoming_calls: Functions that call this
  - outgoing_calls: Functions this calls

Example prompt: "Give me a complete analysis of the processData function at line 75 in /project/src/processor.ts - definition, all references, and what calls it"

Server Management Tools

lsp_server_status

Get status of running language servers.

Input:
  - server_id: Specific server to check (optional, omit for all servers)

Output:
  - servers: Array of server status objects with id, status, capabilities, uptime, etc.

Example prompt: "Show the status of all language servers"

lsp_start_server

Manually start a language server for a specific workspace.

Input:
  - server_id: Server ID from configuration (e.g., 'typescript', 'python')
  - workspace_root: Absolute path to the workspace/project root

Output:
  - status: 'started'
  - server_id: The server that was started
  - workspace_root: The workspace root
  - capabilities: List of supported capabilities

Example prompt: "Start the TypeScript language server for /home/user/my-project"

lsp_stop_server

Stop a running language server.

Input:
  - server_id: Server ID to stop
  - workspace_root: Workspace root (optional, omit to stop all instances)

Output:
  - status: 'stopped'
  - server_id: The server that was stopped
  - was_running: Whether the server was actually running

Example prompt: "Stop the Python language server"

Supported Languages

The following languages are supported out of the box:

Language	Server	Command	File Extensions	Root Patterns
TypeScript/JavaScript	typescript-language-server	typescript-language-server --stdio	.ts, .tsx, .js, .jsx, .mjs, .cjs	tsconfig.json, jsconfig.json, package.json
Python	pylsp	pylsp	.py, .pyi	pyproject.toml, setup.py, requirements.txt, Pipfile
Rust	rust-analyzer	rust-analyzer	.rs	Cargo.toml
Go	gopls	gopls serve	.go	go.mod, go.work
C/C++	clangd	clangd --background-index	.c, .h, .cpp, .hpp, .cc, .cxx	compile_commands.json, CMakeLists.txt, Makefile
Ruby	solargraph	solargraph stdio	.rb, .rake, .gemspec	Gemfile, .ruby-version, Rakefile
PHP	intelephense	intelephense --stdio	.php, .phtml	composer.json, index.php
Elixir	elixir-ls	elixir-ls	.ex, .exs, .heex, .leex	mix.exs, .formatter.exs

You can add additional languages by providing a custom configuration (see Configuration).

Configuration

Configuration File

Create a configuration file at one of these locations (in order of priority):

1. ./.lsp-mcp.json (current directory)
2. ./lsp-mcp.json (current directory)
3. ~/.config/lsp-mcp/config.json (XDG config)
4. ~/.lsp-mcp.json (home directory)

Example configuration:

{
  "servers": [
    {
      "id": "typescript",
      "extensions": [".ts", ".tsx", ".js", ".jsx"],
      "languageIds": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "rootPatterns": ["tsconfig.json", "package.json"]
    },
    {
      "id": "python",
      "extensions": [".py"],
      "languageIds": ["python"],
      "command": "pylsp",
      "args": [],
      "rootPatterns": ["pyproject.toml", "setup.py", "requirements.txt"]
    }
  ],
  "requestTimeout": 30000,
  "autoStart": true,
  "logLevel": "info",
  "idleTimeout": 1800000
}

Configuration Options

Option	Type	Default	Description
servers	array	Built-in defaults	Language server configurations
requestTimeout	number	30000	Request timeout in milliseconds
autoStart	boolean	true	Auto-start servers on first request
logLevel	string	"info"	Log level: debug, info, warn, error
idleTimeout	number	1800000	Idle timeout before stopping servers (30 min)

Server Configuration

Each server in the servers array has:

Option	Type	Required	Description
id	string	Yes	Unique identifier for the server
extensions	string[]	Yes	File extensions this server handles
languageIds	string[]	Yes	LSP language identifiers
command	string	Yes	Command to start the server
args	string[]	Yes	Command arguments
env	object	No	Environment variables
initializationOptions	object	No	LSP initialization options
rootPatterns	string[]	No	Files/dirs that indicate project root

Environment Variables

Variable	Description
LSP_MCP_LOG_LEVEL	Override log level (debug, info, warn, error)
LSP_MCP_REQUEST_TIMEOUT	Override request timeout in milliseconds
LSP_CONFIG_PATH	Path to configuration file
LSP_WORKSPACE_ROOT	Override workspace root detection

Usage Examples with Claude Code

Basic Navigation

"I'm looking at /project/src/services/auth.ts. Can you tell me what the validateToken function at line 45 does? Use lsp_hover to get its documentation."

"Go to the definition of UserRepository used at line 23, column 15 in /project/src/controllers/user.ts"

Finding Usages

"Find all places where the handleError function is called in my codebase. It's defined at line 10 in /project/src/utils/error.ts"

"I want to refactor the Config interface. First, find all its implementations using lsp_find_implementations"

Code Quality

"Check /project/src/index.ts for any TypeScript errors using lsp_diagnostics"

"Show me all errors and warnings in /project/src/components/Form.tsx"

Safe Refactoring

"I want to rename the getData function to fetchData. It's at line 50 in /project/src/api.ts. First do a dry run to see what would change."

"The dry run looks good. Now apply the rename by setting dry_run to false."

Code Exploration

"List all the symbols in /project/src/models/User.ts to understand its structure"

"Search the workspace for all classes that contain 'Controller' in their name"

Completions

"What methods are available on the object at line 30, column 5 in /project/src/app.ts? Use lsp_completions"

Code Actions and Refactoring

"What refactoring options are available for the code selection from line 20 to 35 in /project/src/utils.ts?"

"Organize imports in /project/src/components/App.tsx using lsp_code_actions with kinds filter for source.organizeImports"

"Apply the quick fix for the error at line 15 in /project/src/api.ts"

Understanding Code Flow

"Show me the call hierarchy for the processOrder function at line 50 in /project/src/orders.ts - I want to see what calls it"

"What does the authenticate function call? Use lsp_call_hierarchy with outgoing direction"

"Show me the type hierarchy for the BaseRepository class - what are its subtypes?"

Comprehensive Analysis

"Give me a complete analysis of the UserService class at line 10 in /project/src/services/user.ts - I want definition, all references, implementations, and call hierarchy. Use lsp_smart_search"

Formatting

"Format /project/src/unformatted.ts using the language server (preview first, don't apply)"

Troubleshooting

Language Server Not Found

Error: Failed to start language server: typescript-language-server

Solution: Install the language server:

npm install -g typescript-language-server typescript

No Diagnostics Showing

Issue: lsp_diagnostics returns empty results

Explanation: Diagnostics are push-based. The language server sends them when files are opened or changed.

Solution:

1. Open the file using another tool first
2. Wait a moment for the server to analyze
3. Try again

Server Crashes Repeatedly

Issue: Server keeps crashing and restarting

Solution:

1. Check LSP_MCP_LOG_LEVEL=debug for detailed logs
2. Verify the language server is properly installed
3. Check if the workspace has valid configuration (e.g., tsconfig.json for TypeScript)

Position Errors

Issue: "Invalid position" errors

Remember: All positions are 1-indexed (first line is 1, first column is 1), not 0-indexed.

Timeout Errors

Issue: Requests timing out

Solution: Increase the timeout:

export LSP_MCP_REQUEST_TIMEOUT=60000  # 60 seconds

Or in configuration:

{
  "requestTimeout": 60000
}

Development

Building

npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run typecheck    # Type-check only

Testing

npm test             # Run unit tests
npm run test:watch   # Watch mode

Interactive Testing

Use the MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector node dist/index.js

Linting

npm run lint         # Check for issues
npm run lint:fix     # Auto-fix issues

Architecture

Multi-root Workspace Support

Server instances are keyed by (languageId, workspaceRoot) pairs. This means:

• Each workspace gets its own language server instance
• Monorepos work correctly with multiple tsconfig.json files
• Server settings are isolated per workspace

Diagnostics Caching

Unlike other LSP features that are request-based, diagnostics are push-based:

1. Language servers send publishDiagnostics notifications
2. lsp-mcp-server caches these in memory
3. lsp_diagnostics tool reads from the cache

This means diagnostics are available immediately after files are opened, without an explicit request.

Automatic Server Lifecycle

• Servers start automatically when needed (if autoStart: true)
• Crashed servers restart with exponential backoff (max 3 attempts in 5 minutes)
• Idle servers shut down after the configured timeout

License

MIT

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.