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.

🚀 Quick Start

The lsp-mcp-server serves as a bridge between Claude Code and language servers, offering powerful code intelligence features. It supports multiple languages and provides various tools for code navigation, analysis, and refactoring.

✨ Features

• 24 MCP Tools for comprehensive code intelligence.
• 10 Languages Supported out of the box:
  • TypeScript / JavaScript
  • Python
  • Rust
  • Go
  • C / C++
  • Ruby
  • PHP
  • Elixir
  • Kotlin
  • Java
• 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

# Kotlin
# macOS:
brew install JetBrains/utils/kotlin-lsp
# Or download from:
# https://github.com/Kotlin/kotlin-lsp/releases

# Java (requires Java 20+, Maven, npm, protobuf)
git clone https://github.com/idelice/jls
cd jls && ./scripts/build.sh
# Add dist/ to PATH or symlink dist/lang_server_linux.sh as 'jls'

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

💻 Usage Examples

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 across the entire project using lsp_workspace_diagnostics"

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"

"Find the UserService class and tell me everything about it - definition, references, and what calls it"

File Analysis

"What does /project/src/utils/index.ts export?"

"What files depend on /project/src/services/auth.ts? Use lsp_related_files"

"Show me all the imports in /project/src/api/client.ts"

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 first 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)"

📚 Documentation

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"

lsp_find_symbol

Find a symbol by name and get comprehensive information about it - no file path needed.

Input:
  - name: Symbol name to search for (supports fuzzy matching)
  - kind: Filter to specific symbol kind (optional): Class, Function, Interface, etc.
  - 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:
  - query: The symbol that was searched for
  - match: The best matching symbol found
  - matches_found: Number of total matches
  - definition: Where the symbol is defined
  - hover: Type information and documentation
  - references: All usages of the symbol
  - implementations: Implementations (for interfaces)
  - incoming_calls: Functions that call this
  - outgoing_calls: Functions this calls

Example prompt: "Find the UserService class and show me all its references"

File Analysis Tools

lsp_file_exports

Get the public API surface of a file - all exported functions, classes, interfaces, and variables.

Input:
  - file_path: Absolute path to the source file
  - include_signatures: Include type signatures from hover (default: true, slower but more informative)

Output:
  - file: The file path
  - exports: Array of exported items with name, kind, line, column, and signature
  - note: Additional information

Example prompt: "What does /project/src/utils/index.ts export?"

lsp_file_imports

Get all imports and dependencies of a file.

Input:
  - file_path: Absolute path to the source file

Output:
  - file: The file path
  - imports: Array of imports with module, line, symbols, is_type_only, is_dynamic
  - note: Additional information

Example prompt: "What modules does /project/src/api/client.ts import?"

lsp_related_files

Find files connected to a given file - what it imports and what imports it.

Input:
  - file_path: Absolute path to the source file
  - relationship: Which relationships to include: 'imports', 'imported_by', or 'all' (default: 'all')

Output:
  - file: The file path
  - imports: Array of files this file imports
  - imported_by: Array of files that import this file
  - note: Additional information

Example prompt: "What files depend on /project/src/services/auth.ts?"

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"

lsp_workspace_diagnostics

Get diagnostics across all open files in the workspace.

Input:
  - severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')
  - limit: Maximum diagnostics to return (default: 50, max: 200)
  - group_by: How to group results - 'file' or 'severity' (default: 'file')

Output:
  - items: Array of diagnostics with file, line, column, severity, message, and context
  - total_count: Total diagnostics found
  - returned_count: Number returned (may be limited)
  - files_affected: Number of files with diagnostics
  - summary: Count of errors, warnings, info, and hints
  - note: Information about diagnostic caching

Example prompt: "Show me all errors across the entire project"

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, and optionally apply them.

Input:
  - file_path: Absolute path to the source file
  - start_line: Start line number (1-indexed)
  - start_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: If true, apply the action at action_index (default: false)
  - action_index: Index of action to apply when apply=true (default: 0)

Output:
  - actions: Array of available code actions with title, kind, and edits
  - total_count: Number of available actions
  - applied: The action that was applied (if apply=true and successful)

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

Example prompt: "Apply the first quick fix for the error at line 15 in /project/src/api.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:

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)

Or set LSP_CONFIG_PATH environment variable to specify a custom path.

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

Server Configuration

Each server in the servers array has:

Environment Variables

🔧 Technical Details

Multi-root Workspace Support

Server instances are keyed by (serverId, 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 and lsp_workspace_diagnostics tools read 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

This project is licensed under the MIT License.

Contributing

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

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

Path Errors

Issue: "File path must be absolute" errors

Remember: All file paths must be absolute (e.g., /home/user/project/src/file.ts, not src/file.ts).

Timeout Errors

Issue: Requests timing out

Solution: Increase the timeout:

export LSP_REQUEST_TIMEOUT=60000  # 60 seconds

Or in configuration:

{
  "requestTimeout": 60000
}

File Too Large

Issue: "File too large" errors

Explanation: Files larger than 10 MB are rejected to prevent memory issues.

Solution: Work with smaller files or split large files into modules.

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

Version

Current version: 1.1.11