Claude Code에 Serena MCP 연동하기 - Java/TypeScript LSP 설정

grep 방식의 한계를 넘어, Serena MCP로 LSP 기반 심볼 탐색을 Claude Code에 연동하는 방법을 Java/TypeScript 프로젝트 기준으로 설치부터 실전 활용까지 정리했습니다.

들어가며 - grep의 한계

한 줄 요약: Serena MCP를 Claude Code에 연동하면 grep 대신 LSP 기반 심볼 검색으로 대형 Java/TypeScript 코드베이스를 훨씬 정확하게 탐색할 수 있습니다.

Claude Code로 레거시 코드를 보다 보면 어느 순간 이런 상황이 옵니다. 특정 메서드를 고쳐야 하는데, 그게 어디서 호출되는지를 파악하는 데 더 오래 걸리는 거죠. Claude Code가 내부적으로 grep과 파일 탐색을 쓰는데, 코드베이스가 크면 누락이 생깁니다. 저도 리팩터링하다가 한 군데를 빠뜨려서 배포 후에야 발견한 적이 있어요.

Serena MCP를 써봤습니다. LSP(Language Server Protocol) 기반이라 심볼 단위로 분석하는데, IDE에서 "참조 찾기"를 누르는 것과 같은 수준으로 탐색이 됩니다. Java와 TypeScript 프로젝트를 기준으로 제가 실제로 세팅한 과정을 정리했습니다. 설치부터 매일 쓰는 루틴까지 그대로 씁니다.

전체 구조 이해하기

세팅하기 전에 구조를 한 번 파악해두면 나중에 문제가 생겼을 때 대처하기 훨씬 쉽습니다.

Claude Code, Serena MCP Server, Project Server(LSP) 3계층 연동 구조를 나타낸 인포그래픽 다이어그램 — 클로드 코드와 Serena MCP 통합 구조

레이어가 세 개입니다. Claude Code가 MCP 클라이언트 역할을 하고, Serena MCP Server가 중간에서 파일 기반 도구는 직접 처리하고 LSP 요청은 Project Server로 넘깁니다. Project Server는 포트 24225에서 따로 돌면서 JDTLS 같은 Language Server를 통해 실제 심볼 분석을 합니다.

처음에 저도 헷갈렸던 부분인데, search_for_pattern이나 find_file은 Project Server 없이도 됩니다. 하지만 find_symbol, find_referencing_symbols 같은 LSP 도구는 Project Server가 떠 있어야만 동작합니다. "왜 빈 배열이 나오지?" 싶으면 십중팔구 이 문제입니다.

설치 및 MCP 등록

사전 요구사항

Claude Code (최신 버전)
Python 환경 (uvx 사용 가능해야 함)
Java 프로젝트라면 build.gradle 또는 pom.xml 존재

Serena 설치

먼저 Serena GitHub 리포지토리의 설치 가이드를 따라 Serena를 설치합니다. uvx를 쓰기 때문에 별도 빌드 없이 바로 실행됩니다.

Claude Code에 MCP 등록

프로젝트 루트 디렉토리로 이동한 뒤 아래 명령어를 실행합니다.

# 프로젝트 루트에서 실행 — 최초 1회만
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"

이 명령은 최초 1회만 실행하면 됩니다. Claude Code 설정에 저장되어 이후에는 자동으로 연결됩니다. 등록 후 Claude Code를 재시작하면 /mcp 명령으로 Serena 연결 상태를 확인할 수 있습니다.

참고로, 연결이 안 될 때는 /mcp → Serena 선택 → Reconnect를 먼저 시도해보세요. 그래도 안 된다면 Claude Code를 완전히 종료(/exit)하고 재시작하는 게 가장 확실합니다.

프로젝트 추가하기

MCP 연결이 완료되면 Serena는 루트 프로젝트를 자동으로 인식합니다. 모노레포를 사용하는 경우 서브 프로젝트는 Claude Code에게 요청하면 알아서 추가해줍니다.

> 세레나에 backend/spring-tomcat/api 프로젝트 추가해줘

추가된 프로젝트는 ~/.serena/serena_config.yml의 projects 리스트에 자동으로 저장됩니다.

# ~/.serena/serena_config.yml
projects:
  - /home/user/workspace/my-monorepo
  - /home/user/workspace/my-monorepo/backend/api
  - /home/user/workspace/my-monorepo/backend/nestjs/service
  - /home/user/workspace/my-monorepo/frontend/web

물론 이 파일을 직접 편집해서 프로젝트를 추가할 수도 있습니다. 어느 방법이든 결과는 동일합니다.

프로젝트 추가 후 반드시 클로드를 재시작하거나 /mcp 커맨드로 Serena를reconnect 해주세요.

Language Server 설정

Java

프로젝트에 build.gradle이나 pom.xml이 있으면 자동으로 Java(Eclipse JDTLS)를 인식합니다. 별도 설정 없이 바로 find_symbol 등 LSP 도구를 쓸 수 있습니다.

TypeScript

저는 대시보드에서 언어를 먼저 추가한 뒤 프로젝트를 등록했기 때문에, 자동 감지 여부는 확인하지 못했습니다. 일단 대시보드 수동 추가 기준으로 설명합니다.

브라우저에서 http://localhost:24282/dashboard/ 접속
Add Language 클릭
TypeScript 선택

대시보드 URL이 기억 안 날 때는 serena_config.yml의 web_dashboard_open_on_launch: true 옵션을 켜두면 Project Server 시작 시 브라우저가 자동으로 열립니다.

설정 파일 직접 편집하기

~/.serena/serena_config.yml을 편집하면 Serena의 세부 동작을 조정할 수 있습니다. 제가 실제로 쓰는 설정을 기준으로 설명합니다.

# Language Backend 설정 (LSP 또는 JetBrains IDE 플러그인)
language_backend: LSP

# 웹 대시보드
web_dashboard: true
web_dashboard_open_on_launch: true   # 시작 시 브라우저 자동 오픈

# 로그 레벨 (10=debug, 20=info, 30=warning, 40=error)
log_level: 20

# LSP 통신 디버깅 — Language Server 문제 발생 시 true로 바꿔서 확인
trace_lsp_communication: false

# 분석이 불필요한 경로 제외 (빌드 산출물 등)
ignored_paths:
  - "**/build/**"
  - "**/.gradle/**"
  - "**/.idea/**"
  - "**/node_modules/**"
  - "**/out/**"
  - "**/bin/**"

# 기본 활성화 모드
default_modes:
  - interactive    # 대화형 작업
  - editing        # 코드 편집 허용
  - query-projects # 서브 프로젝트 쿼리 허용

설정 변경 후에는 Claude Code를 재시작해야 반영됩니다. /reload-plugins로는 LSP 연결이 끊기는 부작용이 있으니 완전 재시작을 권장합니다.

Project Server 시작하기

find_symbol, find_referencing_symbols 등 LSP 기반 도구를 쓰려면 Project Server를 별도로 실행해야 합니다. 터미널을 하나 더 열고 아래 명령을 실행합니다.

# 별도 터미널에서 실행 — 이 창은 닫지 않기
uvx --from git+https://github.com/oraios/serena serena start-project-server --port 24225

처음 시작하면 등록된 프로젝트 전체를 인덱싱합니다. 터미널에 아래와 같은 로그가 한동안 반복 출력됩니다.

INFO [LSP-stdout-reader:java] - Reconciled 1. Took 0 ms
INFO [LSP-stdout-reader:java] - Reconciled 1. Took 2 ms
...

이건 파일을 하나씩 분석하는 정상 동작입니다. 로그가 멈추면 인덱싱 완료입니다. 코드베이스 크기에 따라 수 분이 걸릴 수 있는데, 이게 끝나야 LSP 도구가 제대로 동작하니 그냥 기다리면 됩니다.

주요 도구 정리

Serena가 제공하는 도구는 크게 두 종류입니다. Project Server 필요 여부가 다르기 때문에 구분해서 알아두면 좋습니다.

LSP 기반 도구 (Project Server 필요)

도구	용도	예시
`find_symbol`	클래스/메서드 검색	`MypageHelper/login`
`query_project`	서브 프로젝트에서 심볼 검색	api 프로젝트의 `MypageHelper`
`find_referencing_symbols`	참조 추적 (어디서 호출하는지)	`login`을 호출하는 모든 곳
`replace_symbol_body`	심볼 코드 교체	메서드 본문 수정
`get_symbols_overview`	파일 내 심볼 목록 조회	클래스의 메서드 전체 확인

파일 기반 도구 (Project Server 불필요)

도구	용도	예시
`search_for_pattern`	정규식 패턴 검색	`mypageHelper\.login\(`
`find_file`	파일명으로 검색	`MypageHelper*`
`list_dir`	디렉토리 목록 조회	프로젝트 구조 파악

실무에서 가장 많이 쓰게 되는 건 find_referencing_symbols입니다. "이 메서드 이름 바꾸면 어디어디 수정해야 하지?"할 때 바로 답이 나옵니다.

매일 시작하는 순서

MCP 등록은 최초 1회만 하면 됩니다. 그 이후 매일 개발을 시작할 때는 아래 순서만 따르면 됩니다.

# Step 1. Project Server 시작 (별도 터미널 — 닫지 않기)
uvx --from git+https://github.com/oraios/serena serena start-project-server --port 24225

# Step 2. Claude Code 시작
cd ~/workspace/my-project
claude

# Step 3. MCP 연결 확인
# Claude Code 내에서: /mcp → Serena 상태 확인
# 연결이 안 됐다면 Reconnect 클릭

Project Server의 인덱싱이 완료되기 전에 LSP 도구를 쓰면 빈 결과가 반환됩니다. 터미널의 Reconciled 로그가 멈출 때까지 잠깐 기다렸다가 작업을 시작하는 게 좋습니다.

트러블슈팅

① `ProjectServer is not reachable at http://127.0.0.1:24225`

Project Server가 실행 중이지 않은 경우입니다. 별도 터미널에서 시작해주세요.

uvx --from git+https://github.com/oraios/serena serena start-project-server --port 24225

② MCP 연결이 안 될 때

/mcp → Serena 선택 → Reconnect를 먼저 해보고, 그래도 안 되면 Claude Code를 완전히 종료(/exit)하고 재시작하는 게 제일 확실합니다.

③ `/reload-plugins` 후 LSP 도구가 안 됨

플러그인 리로드 시 LSP 연결이 끊깁니다. MCP 재연결만으로는 복구가 안 되고, Claude Code 완전 종료 후 재시작해야 합니다.

④ `find_symbol` 결과가 빈 배열 `[]`

원인이 대체로 세 가지입니다. 루트에서 검색했는데 실제 소스는 서브 프로젝트에 있는 경우라면 query_project로 대상을 지정해보세요. LSP 인덱싱이 아직 안 끝난 경우라면 Reconciled 로그가 멈출 때까지 기다리면 됩니다. 심볼명이 정확하지 않은 경우엔 substring_matching: true 옵션을 써보세요.

⑤ 포트 충돌

이전 프로세스가 포트를 잡고 있는 경우입니다.

# 포트 점유 확인
netstat -an | grep 24225

마무리

Serena 쓰면서 가장 달라진 건 "이 메서드 어디서 쓰이지?"를 Claude Code한테 묻고 또 묻는 루프가 없어졌다는 겁니다. grep 탐색은 누락이 생기면 다시 찾고 또 확인하고를 반복했는데, LSP 기반이면 그냥 한 번에 나옵니다.

다만 솔직히 말하면 세팅이 좀 귀찮습니다. Project Server를 따로 띄워야 하고, 처음 인덱싱도 기다려야 합니다. 규모가 작은 프로젝트라면 굳이 도입할 이유는 없어요. 수십만 라인 이상 되는 레거시를 Claude Code로 분석하거나 리팩터링할 때 효과가 납니다.

한 번 세팅해두면 매일 하는 건 터미널 두 개 열고 명령어 두 개 입력하는 게 전부라, 진입 장벽에 비해 쓰는 건 단순합니다.

참고 자료

저작자표시 비영리 변경금지 (새창열림)

'AI' 카테고리의 다른 글

Claude Code CLAUDE.md: 팀 지침을 위한 계층 구조와 스킬 분리 실전 적용기 (1)	2026.03.11
Gemini CLI에 Serena MCP 연동하기 - Git Clone 방식 실전 설정 (1)	2026.03.08
Gemini CLI sessionId 추출 및 DB 관리 가이드: 여러 AI 에이전트 협업 시스템 구축하기 (0)	2026.03.04
Claude Code 회사/개인 환경 분리하기 - CLAUDE_CONFIG_DIR부터 WSL까지 (0)	2026.02.20
Claude Code Hooks로 자동화하기 - 실수 방지부터 작업 기록까지 (0)	2026.01.26

CodeVibe

Claude Code에 Serena MCP 연동하기 - Java/TypeScript LSP 설정

목차

들어가며 - grep의 한계

전체 구조 이해하기

설치 및 MCP 등록

사전 요구사항

Serena 설치

Claude Code에 MCP 등록

프로젝트 추가하기

Language Server 설정

Java

TypeScript

설정 파일 직접 편집하기

Project Server 시작하기

주요 도구 정리

LSP 기반 도구 (Project Server 필요)

파일 기반 도구 (Project Server 불필요)

매일 시작하는 순서

트러블슈팅

① `ProjectServer is not reachable at http://127.0.0.1:24225`

② MCP 연결이 안 될 때

③ `/reload-plugins` 후 LSP 도구가 안 됨

④ `find_symbol` 결과가 빈 배열 `[]`

⑤ 포트 충돌

마무리

참고 자료

'AI' 카테고리의 다른 글

티스토리툴바

Claude Code에 Serena MCP 연동하기 - Java/TypeScript LSP 설정

목차

들어가며 - grep의 한계

전체 구조 이해하기

설치 및 MCP 등록

사전 요구사항

Serena 설치

Claude Code에 MCP 등록

프로젝트 추가하기

Language Server 설정

Java

TypeScript

설정 파일 직접 편집하기

Project Server 시작하기

주요 도구 정리

LSP 기반 도구 (Project Server 필요)

파일 기반 도구 (Project Server 불필요)

매일 시작하는 순서

트러블슈팅

① ProjectServer is not reachable at http://127.0.0.1:24225

② MCP 연결이 안 될 때

③ /reload-plugins 후 LSP 도구가 안 됨

④ find_symbol 결과가 빈 배열 []

⑤ 포트 충돌

마무리

참고 자료

'AI' 카테고리의 다른 글

관련글

티스토리툴바

① `ProjectServer is not reachable at http://127.0.0.1:24225`

③ `/reload-plugins` 후 LSP 도구가 안 됨

④ `find_symbol` 결과가 빈 배열 `[]`