MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

L
Lsp MCP Server
by @ProfessioneIT
GitHub Repo(1 stars)
Website

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

Created 1/26/2026
Updated 2 days ago
README
View Source
Repository documentation and setup instructions

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.

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-lsp-mcp-server

Cursor configuration (mcp.json)

{ "mcpServers": { "professioneit-lsp-mcp-server": { "command": "npx", "args": [ "professioneit-lsp-mcp-server" ] } } }