Which integrations are available for this server?

Provides semantic code intelligence for C++ projects, including navigation, code completion, diagnostics, and refactoring through clangd. Provides semantic code intelligence for Elixir projects, including navigation, completion, and diagnostics using ElixirLS. Provides semantic code intelligence for JavaScript projects, including navigation, completion, and symbol search via the TypeScript Language Server. Provides semantic code intelligence for PHP projects, including navigation, completion, and diagnostics using Intelephense. Provides semantic code intelligence for Python projects, including navigation, completion, and diagnostics via the Python LSP server. Provides semantic code intelligence for Ruby projects, including navigation, completion, and diagnostics using Solargraph. Provides semantic code intelligence for Rust projects, including navigation, completion, and diagnostics using rust-analyzer. Provides semantic code intelligence for TypeScript projects, including navigation, completion, symbol search, and refactoring via the TypeScript Language Server.

How do I use lsp-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lsp-mcp-server Find all references to the validateInput function in src/utils.ts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

`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):

./.lsp-mcp.json (current directory)
./lsp-mcp.json (current directory)
~/.config/lsp-mcp/config.json (XDG config)
~/.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

"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:

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

Server Crashes Repeatedly

Issue: Server keeps crashing and restarting

Solution:

Check LSP_MCP_LOG_LEVEL=debug for detailed logs
Verify the language server is properly installed
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:

Language servers send publishDiagnostics notifications
lsp-mcp-server caches these in memory
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.