Lsp MCP Server

🚀 lsp-mcp-server

lsp-mcp-server serves as a bridge between Claude Code and language servers, offering powerful code intelligence features. It enables seamless navigation, reference finding, and code analysis across multiple programming languages, enhancing the development experience.

🚀 Quick Start

lsp-mcp-server is a tool that connects Claude Code with various language servers, providing a wide range of code intelligence capabilities. To get started, follow the installation and configuration steps below.

✨ Features

• 24 MCP Tools: Offer comprehensive code intelligence, including navigation, reference finding, information retrieval, and more.
• 10 Languages Supported: Out of the box support for TypeScript/JavaScript, Python, Rust, Go, C/C++, Ruby, PHP, Elixir, Kotlin, and Java.
• Multi-root Workspace: Properly supports monorepos with per - workspace server instances.
• Push-based Diagnostics: Real - time caching of errors and warnings 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: Include file size limits, workspace boundary validation, and 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

• lsp_goto_type_definition: Navigate to the type 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 type definition locations

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

• 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

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)

• 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

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

• 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

• lsp_find_symbol: Find a symbol by name and get comprehensive information about it.

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

File Analysis Tools

• lsp_file_exports: Get the public API surface of a file.

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

• 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

• lsp_related_files: Find files connected to a given file.

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

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

• 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

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

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)

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

• 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

Hierarchy Tools

• lsp_call_hierarchy: Get the call hierarchy for a function.

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

• lsp_type_hierarchy: Get the type hierarchy for a class or interface.

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

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

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.

• 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

• 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

Supported Languages

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.

Version

Current version: 1.1.11

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