Claude Code에서 LSP 설정하기

Claude Code는 기본적으로 코드베이스를 탐색할 때 grep과 glob을 써요. 텍스트 검색이라 "이 함수 정의가 어디 있지?"라고 물으면 여러 매치를 하나씩 읽어 가며 찾아요. LSP를 연결하면 IDE의 "Go to Definition"처럼 심볼 단위로 바로 찾을 수 있어요.

이 글에서는 Claude Code에 LSP를 연결하는 방법(언어 서버 설치 + 플러그인 설치)을 정리했어요.

LSP란?

Language Server Protocol은 Microsoft가 2016년에 발표한 프로토콜이에요. 에디터와 언어 서버 사이의 통신 규약으로, VS Code에서 함수 위에 마우스를 올리면 타입 정보가 뜨고, "Go to Definition"으로 정의로 이동하고, 빨간 밑줄로 에러를 알려주는 기능이 LSP로 동작해요.

Claude Code에 LSP를 연결하면 Claude도 같은 기능을 써요:

편집 후 진단 — Claude가 파일을 수정할 때마다 언어 서버가 보고한 타입 에러, 누락된 import 같은 문제를 바로 받아요
코드 탐색 — LSP 도구로 정의 찾기, 참조 찾기, 타입 정보 확인, 파일 안의 심볼 목록, 워크스페이스 심볼 검색, 구현 찾기, 호출 계층 추적을 해요. 이 도구는 읽기 전용이에요

사전 준비

LSP 도구는 Claude Code v2.0.74에서 추가됐어요 (claude --version으로 확인)
터미널에서 실행하는 세션이어야 해요. 클라우드 세션(claude.ai/code 등)에서는 플러그인 언어 서버가 시작되지 않아요
별도 환경변수는 필요 없어요. 공식 문서 기준으로 언어 서버 바이너리와 플러그인만 설치하면 LSP 도구가 켜져요

Step 1: 언어 서버 바이너리 설치

플러그인은 언어 서버를 어떤 명령으로 띄울지만 알려주고, 언어 서버 자체는 들어 있지 않아요. 그래서 바이너리를 먼저 설치해요.

TypeScript / JavaScript

Bash

npm install -g typescript-language-server typescript

Python

Bash

npm install -g pyright
# 또는
pip install pyright

pyright-langserver 명령이 생기면 돼요.

Go

Bash

go install golang.org/x/tools/gopls@latest

$GOPATH/bin이 $PATH에 포함되어 있는지 확인하세요.

Rust

Bash

rustup component add rust-analyzer

공식 플러그인이 있는 언어

언어	플러그인	바이너리
C/C++	`clangd-lsp`	`clangd`
C#	`csharp-lsp`	`csharp-ls`
Go	`gopls-lsp`	`gopls`
Java	`jdtls-lsp`	`jdtls`
Kotlin	`kotlin-lsp`	`kotlin-lsp`
Lua	`lua-lsp`	`lua-language-server`
PHP	`php-lsp`	`intelephense`
Python	`pyright-lsp`	`pyright-langserver`
Ruby	`ruby-lsp`	`ruby-lsp`
Rust	`rust-analyzer-lsp`	`rust-analyzer`
Swift	`swift-lsp`	`sourcekit-lsp`
TypeScript / JavaScript	`typescript-lsp`	`typescript-language-server`

설치한 뒤에는 claude를 실행하는 쉘의 PATH에 있는지 확인해요 (예: which typescript-language-server).

Step 2: LSP 플러그인 설치

LSP 플러그인은 Anthropic 공식 마켓플레이스(claude-plugins-official)에 있어요. 공식 마켓플레이스는 처음 터미널 세션을 시작할 때 자동으로 등록돼요.

세션 안에서 설치

TEXT

/plugin install typescript-lsp@claude-plugins-official

/plugin만 입력하면 Discover 탭에서 검색해서 고를 수도 있어요. 설치할 때 범위(user / project / local)를 골라요.

CLI로 직접 설치

Bash

claude plugin install pyright-lsp@claude-plugins-official
claude plugin install typescript-lsp@claude-plugins-official
claude plugin install gopls-lsp@claude-plugins-official

쉘에서 설치한 플러그인은 다음에 Claude Code를 시작할 때, 또는 열려 있는 세션에서 /reload-plugins를 실행하면 로드돼요.

서드파티 마켓플레이스 (선택사항)

Dart처럼 공식 플러그인이 없는 언어는 커뮤니티 마켓플레이스를 쓸 수 있어요:

Bash

claude plugin marketplace add boostvolt/claude-code-lsps

claude plugin marketplace add Piebald-AI/claude-code-lsps

Anthropic은 서드파티 마켓플레이스를 검토하지 않으니, 추가하기 전에 내용을 확인하세요. 직접 .lsp.json을 쓴 플러그인을 만들어 연결할 수도 있어요.

플러그인 활성화 확인

Bash

claude plugin list
# Status: disabled인 플러그인이 있다면:
claude plugin enable <플러그인명>

user 범위로 설치하면 ~/.claude/settings.json의 enabledPlugins에 기록돼요:

JSON

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true
  }
}

Step 3: 동작 확인

언어 서버는 Claude가 해당 확장자의 파일을 처음 편집할 때 시작돼요. 확인하려면 Claude에게 그 언어 파일에 타입 에러를 하나 넣었다가 고쳐 달라고 해 보세요.

편집 아래에 Found N new diagnostic issues in M files (ctrl+o to expand)가 보이면 서버가 시작된 거예요. Ctrl+O로 내용을 볼 수 있어요.
이 줄이 안 보이면 /plugin의 Errors 탭을 열어요. Executable not found in $PATH: "<바이너리>"가 있으면 그 바이너리를 설치해요.

탐색은 이렇게 물어보면 돼요:

TEXT

> 이 프로젝트에서 ConfigManager 클래스가 어디에 정의되어 있어?

트러블슈팅

증상	해결 방법
진단 줄이 안 나옴	바이너리가 `$PATH`에 있는지, 플러그인이 enabled인지 확인
플러그인 설치 후에도 동작 안 함	`/reload-plugins` 실행 또는 Claude Code 재시작
`/plugin` Errors 탭에 "Executable not found"	Language Server 바이너리 설치 및 PATH 확인 후, `PATH`가 맞는 쉘에서 새 세션 시작
LSP가 가끔만 사용됨	`CLAUDE.md`에 "코드 탐색 시 LSP를 우선 사용하세요" 지시를 추가

CLAUDE.md에 LSP 우선 사용 지시 추가

Claude가 정의를 찾을 때도 grep을 먼저 쓰는 경우가 있어요. LSP를 더 자주 쓰게 하려면 프로젝트 루트의 CLAUDE.md에 다음을 추가해 보세요:

Markdown

## 코드 탐색

- 함수 정의 찾기, 참조 탐색, 타입 확인 시 LSP 도구를 우선 사용하세요.
- grep/glob은 텍스트 검색이나 파일 탐색에만 사용하세요.

그래도 항상 LSP를 쓰지는 않아요. 텍스트 검색이 필요한 곳에는 여전히 grep이 쓰여요.

마무리

언어 서버 바이너리를 설치하고 공식 마켓플레이스에서 해당 언어의 LSP 플러그인을 설치하면, Claude가 편집 직후 진단을 받고 심볼 단위로 코드를 찾을 수 있어요.