MCP Server for LSP Code Intelligence (karellen-lsp-mcp)

Overview

karellen-lsp-mcp gives LLM clients structured code intelligence via LSP (Language Server Protocol) servers. Instead of reading through entire codebases, the LLM can query definitions, references, call hierarchies, type hierarchies, hover documentation, symbols, and diagnostics — the same information a human developer gets from their IDE.

Two interfaces, one daemon:

• MCP interface (karellen-lsp-mcp): Explicit tool calls with structured responses. Requires MCP tool approval or allow-rules.
• LSP proxy interface (karellen-lsp): Native LSP server that Claude Code uses transparently — no permission prompts, no manual project registration. Auto-detects languages and routes to backend LSP servers.

Architecture

Multiple Claude sessions share a single daemon process and a single LSP server per project, avoiding duplicate server instances and redundant indexing:

Claude Code LSP           Claude MCP Session 1      Claude MCP Session 2
     │ (stdio)                  │ (stdio)                  │ (stdio)
     ▼                          ▼                          ▼
┌─────────────┐          ┌─────────────┐          ┌─────────────┐
│  LSP proxy  │          │  MCP stdio  │          │  MCP stdio  │
│  frontend   │          │  frontend   │          │  frontend   │
└──────┬──────┘          └──────┬──────┘          └──────┬──────┘
       │ (Unix socket)          │                        │
       ▼                        ▼                        ▼
┌──────────────────────────────────────────────────────────────┐
│     karellen-lsp-mcp daemon                                  │
│                                                              │
│  Project Registry (refcounted)                               │
│    project-A  refcount=3  ──► clangd                         │
│    project-B  refcount=1  ──► jdtls                          │
└──────────────────────────────────────────────────────────────┘

• Daemon: Persistent process, owns all LSP server subprocesses and the project registry. Listens on Unix domain socket. User-scoped. Auto-starts when the first frontend connects, auto-exits after idle timeout with no connections.
• MCP frontend: Thin stdio process per Claude session. Connects to daemon, proxies MCP tool calls. Returns structured data (dataclasses) for fast LLM processing.
• LSP proxy frontend: Standard LSP server over stdio. Auto-detects languages on initialize, registers projects, routes LSP requests to the correct backend. Reuses the same adapters, normalizers, and readiness tracking as MCP.

Supported Languages

| Language | Default LSP Server | Autodetection | Details | |----------|-------------------|---------------|---------| | C / C++ | clangd | CMake, Meson, autotools, Make, Bazel | docs/c-cpp.md | | Java / Kotlin | jdtls | Gradle, Maven, Ant | docs/java-kotlin.md | | Python | pyright | PyBuilder, pyproject.toml, setup.py, Pipfile, requirements.txt | docs/python.md | | Rust | rust-analyzer | Cargo.toml, workspace detection | docs/rust.md | | Any | Custom via lsp_command parameter | — | Provide the command in lsp_register_project |

Projects are autodetected when language is omitted from lsp_register_project, or inspected explicitly via lsp_detect_project. Detection scans build system markers, IDE metadata (JetBrains .idea/, Eclipse, VS Code), and source file conventions.

Requirements

• Python >= 3.10
• An LSP server for your language, installed and on PATH
• Linux or macOS (uses Unix domain sockets; Windows 10 build 17063+ also works)

Installation

pip install --user karellen-lsp-mcp

Install with LSP server dependencies:

pip install --user karellen-lsp-mcp[clangd]         # C/C++ support
pip install --user karellen-lsp-mcp[jdtls]          # Java/Kotlin support
pip install --user karellen-lsp-mcp[pyright]        # Python support
pip install --user karellen-lsp-mcp[all]            # All LSP servers
# Rust: rustup component add rust-analyzer

Or with pipx for an isolated environment:

pipx install 'karellen-lsp-mcp[all]'

Claude Code Integration

Plugin Installation (Recommended)

The plugin provides both interfaces in one package:

• Native LSP server (karellen-lsp): Transparent code intelligence — Claude Code uses it automatically for supported file types. No permission prompts, no manual registration. Auto-detects languages from CWD and routes to backend LSP servers.
• MCP tools (karellen-lsp-mcp): Explicit tool calls with structured responses, plus hooks (prerequisite checks, compiler error detection), skills (/karellen-lsp-mcp:lsp-register, /karellen-lsp-mcp:lsp-investigate), and an autonomous lsp-investigator agent.

Both share the same daemon — MCP-registered projects are visible to native LSP queries and vice versa.

From Karellen marketplace:

claude plugin marketplace add karellen/claude-plugins
claude plugin install karellen-lsp-mcp@karellen-plugins

From local checkout:

claude --plugin-dir /path/to/karellen-lsp-mcp

Manual MCP Configuration (Alternative)

If you prefer not to use the plugin system, configure the MCP server directly:

claude mcp add --transport stdio karellen-lsp-mcp -- karellen-lsp-mcp

Or manually add to ~/.claude.json (user scope) or .mcp.json in your project root (project scope, shared via version control):

{
  "mcpServers": {
    "karellen-lsp-mcp": {
      "type": "stdio",
      "command": "karellen-lsp-mcp"
    }
  }
}

If installed with pipx:

claude mcp add --transport stdio karellen-lsp-mcp -- pipx run karellen-lsp-mcp

or manually:

{
  "mcpServers": {
    "karellen-lsp-mcp": {
      "type": "stdio",
      "command": "pipx",
      "args": ["run", "karellen-lsp-mcp"]
    }
  }
}

Note: manual MCP configuration provides tools only, without hooks, skills, or agents.

Auto-approve MCP tools

The native LSP interface requires no approval — Claude Code uses it transparently.

For MCP tools, Claude Code prompts for confirmation by default. To auto-approve, add a permission rule to your user settings (~/.claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__karellen-lsp-mcp__*",
      "mcp__plugin_karellen-lsp-mcp_karellen-lsp-mcp__*"
    ]
  }
}

Or for a project-scoped setting, add the same rule to .claude/settings.json in your project root (this file can be committed to version control so all team members get it).

Teach Claude the LSP workflow

Claude will automatically discover all lsp_* tools, but to teach it when and how to use them effectively, add the following to your project's CLAUDE.md:

## LSP Code Intelligence

### When to Use LSP Tools

Use the `lsp_*` MCP tools for navigating and understanding codebases — especially when
you need to trace call chains, find all references to a symbol, understand type
hierarchies, or check compiler diagnostics without reading entire files.

### Setup

Register your project once at the start of a session. Do NOT ask the user for
configuration details. Do NOT narrate intermediate steps. Do the entire setup
(search, generate if needed, register) in one action sequence without pausing for
confirmation.

**C/C++ projects** use clangd as the default LSP server. clangd needs a
`compile_commands.json` for accurate results. Most projects don't have one pre-built.
Do all of this in one go:

1. Search for an existing `compile_commands.json` — use `Glob` to check the project
   tree. Also check if there's an existing build directory (look for `build/`,
   `cmake-build-*/`, `out/`, or a `compile_commands.json` symlink in the project root).
2. If not found, detect the build system and generate it:
   - `CMakeLists.txt` → check if there's already a build directory with cmake cache
     (in-tree or out-of-tree). If an existing build dir has `CMakeCache.txt`, re-run
     cmake there with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`. Otherwise run
     `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build`.
   - `meson.build` → `meson setup build` (generates it automatically)
   - `Makefile`/`configure`/autotools → use Bear if available (`bear -- make`), or
     run `make -n` to get compiler commands and write `compile_commands.json` yourself
   - No build system → register without `build_info` (clangd still works for basics)
3. Register immediately — don't ask for confirmation:

```
lsp_register_project(
    project_path="/path/to/project",
    language="cpp",  # or "c"
    build_info={"compile_commands_dir": "/path/to/dir/containing/compile_commands.json"}
)
```

**Other languages**: pass a custom `lsp_command`:

```
lsp_register_project(
    project_path="/path/to/project",
    language="go",
    lsp_command=["gopls"]
)
```

### Key Rules

- **Use LSP instead of grepping**: `lsp_find_references` is semantically aware — it finds
  actual references, not string matches. It won't return comments, strings, or unrelated
  symbols with the same name
- **Hover before reading**: `lsp_hover` gives you the type signature and documentation
  for any symbol — often enough to understand usage without reading the full definition
- **Call hierarchy for impact analysis**: before changing a function, use
  `lsp_call_tree_incoming` to get the full recursive call tree in one shot, or
  `lsp_call_hierarchy_incoming` for a single level
- **Single-file queries work immediately**: `lsp_read_definition`, `lsp_hover`, and
  `lsp_document_symbols` don't wait for background indexing. Use these freely even on
  large codebases that are still indexing
- **Cross-file queries wait for indexing automatically**: `lsp_find_references`,
  call hierarchy, type hierarchy, and `lsp_diagnostics` wait for indexing to finish,
  with the timeout extending automatically as long as progress is being made. No need
  to poll or sleep. Use `lsp_indexing_status(project_id)` to check progress on large
  codebases
- **All positions are 1-based**: line and character offsets in both input and output
  start at 1. Values from one tool's output (e.g. `lsp_workspace_symbols`) can be
  fed directly into another tool's input (e.g. `lsp_read_definition`)
- **Stale compile_commands.json is auto-detected**: if build config files
  (`CMakeLists.txt`, `meson.build`) are newer than `compile_commands.json`, or
  5% or more of referenced