이제 와서 하는 느낌도 있지만, Serena MCP에 대해 해설하겠습니다.

Serena는 Claude Code와 같은 AI 코딩 에이전트에게 "코드를 구문 레벨(syntax level)로 이해하는 눈"을 부여하는 MCP 서버입니다. grep이 문자의 나열을 찾는다면, Serena는 언어 서버(LSP, Language Server Protocol)를 통해 심볼(함수·클래스·변수)의 정의와 참조를 정확하게 추적합니다.

이 기사대로 진행하면 도입부터 자주 사용하는 조작까지 한 번에 재현할 수 있습니다. 막히는 부분도 메모해 두었습니다. 검증 환경은 Mac + Claude Code + TypeScript 프로젝트이지만, 다른 언어나 에이전트에서도 큰 틀은 동일합니다.

이 기사에서 알 수 있는 것

• Serena가 무엇이며, 어떤 점이 좋은가
• Claude Code로의 도입 (명령어 한 줄)
• 자주 사용하는 기본 도구의 사용법
• 실제로 겪었던 3가지 문제점과 회피 방법

Serena란

Serena는 MCP (Model Context Protocol) 서버 중 하나입니다. 내부에서 LSP를 기동하여 소스 코드를 "심볼의 트리"로 취급합니다. 그 위에서 에이전트에게 심볼 단위의 검색·참조 추적·편집과 같은 도구군을 제공합니다.

grep과 무엇이 다른가

요약하자면, Serena의 장점은 다음 3가지입니다.

• 정의와 참조를 "의미"로 정확하게 추적할 수 있음 (동일한 이름의 다른 대상을 잡지 않음)
• 심볼 단위로 편집할 수 있으므로, 행 번호가 어긋나는 사고가 일어나기 어려움
• 필요한 부분만 읽기 때문에 컨텍스트 (토큰)를 절약할 수 있음

이럴 때 도입한다

Serena는 만능이 아닙니다. 적합한 경우와 그렇지 않은 경우를 미리 파악해 두면 불필요한 도입을 피할 수 있습니다.

도입할 가치가 높은 케이스:

• 중규모 이상의 코드베이스에서 심볼의 정의와 참조를 빈번하게 추적할 때
• 리팩터링(Refactoring)·이름 변경(Rename)·영향 범위 조사가 많을 때
• LSP가 작동하는 정적 타입 언어 (TypeScript, Python, Go, Java 등)
• 큰 파일을 통째로 읽게 하지 않고 토큰을 절약하고 싶을 때

무리하게 도입할 필요가 없는 케이스:

• 소규모·단일 파일 중심이며 표준 grep이나 Read로 충분할 때
• 주로 문장·설정·Markdown을 다루며 코드의 심볼이 적을 때
• LSP 지원이 약하거나 미지원되는 언어일 때

고민된다면 "grep으로 심볼을 추적하는 것이 힘들다고 느껴지기 시작할 때 도입한다" 정도의 온도감이면 충분합니다.

전제 도구

• uv (uvx): Serena는 Python 제이며, uvx를 통해 격리된 환경에서 실행합니다
• Claude Code: 도입되어 있다는 것을 전제로 합니다

uv가 미도입 상태라면 설치해 둡니다.

brew install uv

확인합니다.

uv --version
claude --version

도입 ─ 3단계

1. 대상 프로젝트로 이동

cd /path/to/your-project

2. Serena를 등록하기

프로젝트 내에서 local 스코프에 등록합니다 (claude mcp add의 기본 스코프가 local입니다).

claude mcp add serena -- \
uvx --from git+https://github.com/oraios/serena \
serena start-mcp-server --context claude-code --project "$(pwd)"

• --context claude-code는 코딩 지원을 위한 설정입니다 (구 명칭인 ide-assistant도 작동하지만, 권장되지 않는다는 경고 로그가 나오기 때문에 새로운 기사에서는 claude-code를 사용합니다).
• --project "$(pwd)"로 대상 프로젝트를 고정합니다 ($(pwd)는 실행 시 절대 경로로 전개됩니다).

3. 연결 확인하기

claude mcp list

serena: ... ✔ Connected라고 표시되면 성공입니다. 처음에는 브라우저에 Serena의 대시보드(http://localhost:24282/dashboard/)

）가 열리며, 도구 호출(tool call) 로그를 확인할 수 있습니다.

[!note] 실행 시 열리는 페이지는 닫아도 됩니다

Claude Code를 실행할 때마다 브라우저에서 열리는 것은 Serena의 대시보드(로그 확인용 화면)입니다. Serena 본체는 Claude Code가 실행된 프로세스 내에서 동작하며, 브라우저와는 독립되어 있습니다. 탭을 닫아도 기능은 중단되지 않습니다. 계속 띄워둘 필요는 없습니다.

매번 열리는 것을 중단하고 싶다면 ~/.serena/serena_config.yml에서 web_dashboard_open_on_launch: false로 설정하거나, 화면 자체가 필요 없다면 web_dashboard: false로 설정합니다 (닫거나 비활성화해도 Serena의 동작에는 영향을 주지 않습니다).

등록 후, Serena는 프로젝트 직하에 .serena/를 생성합니다. .serena/cache는 생성물이므로 Git 관리 대상에서 제외합니다 (Serena가 .serena/.gitignore를 준비합니다).

[!note] 글로벌 등록 주의

user 스코프에서 --project /특정경로를 고정하여 등록하면, 다른 프로젝트를 열어도 이전 경로를 계속 붙잡고 있게 됩니다. 등록은 반드시 프로젝트 내에서 local 스코프로 진행해 주세요.

사전 인덱싱 (선택 사항 · 가속화)

심볼 검색(symbol search)을 빠르게 하기 위해, 처음에 색인을 만들어 둡니다.

uvx --from git+https://github.com/oraios/serena serena project index

Indexed files per language: typescript=486와 같이 표시되면 완료입니다. 이후의 검색은 색인 히트(index hit)를 통해 빨라집니다. 규모가 큰 프로젝트일수록 효과가 나타납니다.

[!note] 색인은 가끔 다시 만들기

색인은 특정 시점의 스냅샷입니다. 일상적인 작은 편집에서는 다시 만들 필요가 없으며, 색인에 없는 심볼은 언어 서버(Language Server)가 그 자리에서 찾아내기 때문에 다소 오래되어도 문제가 생기지 않습니다. 다만 다음과 같은 상황에서는 serena project index를 다시 실행하면 검색 누락이나 속도 저하를 방지할 수 있습니다.

• 대규모 리팩터링 (refactoring) 이후
• 파일의 대량 추가 · 이동 · 이름 변경 이후
• 브랜치를 전환하여 코드 구성이 크게 변한 이후
• 심볼 검색이 느리거나 찾을 수 없다고 느껴질 때

색인은 매번 전체를 덮어쓰며 재생성되므로, 언제 실행해도 안전합니다.

사용해 보기

핵심은, 사용자가 직접 도구를 호출하는 것이 아니라 Claude에게 일본어(또는 한국어)로 요청하면 배후에서 Serena의 도구가 실행된다는 점입니다. 다음은 Claude에게 보내는 요청문의 예시입니다.

먼저 파일의 지도를 보기

src/hooks/use-form-submission.ts의 전체상을 알려줘

배후에서 get_symbols_overview가 실행되어 파일 내의 심볼 목록이 반환됩니다. 새로운 파일을 읽을 때의 첫 번째 단계입니다.

심볼 찾기 ─ find_symbol

useFormSubmission이 어디에 있는지 찾아줘

배후에서 find_symbol이 실행되어 정의 위치(파일: 행)가 반환됩니다.

정확도를 높이고 싶을 때는 '이름 경로(name path)'로 타겟팅할 수 있습니다.

자주 사용하는 옵션은 다음과 같습니다.

• relative_path: 탐색 범위를 파일이나 디렉토리로 제한
• depth: 1: 클래스의 자식(메서드 목록)까지 가져오기
• include_body: true: 심볼의 본문 소스(body source)를 가져오기 (읽고 싶을 때만 사용)

호출부 조사하기 ─ find_referencing_symbols

useFormSubmission을 호출하고 있는 곳을 전부 나열해줘

배후에서 find_referencing_symbols가 실행되어 호출부를 정확하게 열거합니다. 이름 변경(rename)이나 영향 범위 조사를 하기 전에 사용하면 안전합니다.

심볼 단위로 편집하기 ─ replace_symbol_body

useHeroHeight의 내용을 (...지시...)와 같이 다시 작성해줘

함수나 클래스를 본체째로 교체합니다. 행 범위(line range)를 지정하는 편집과 달리, 행 번호가 어긋나서 발생하는 사고가 일어나기 어렵다는 것이 장점입니다.

프로젝트의 기억 ─ 메모리 (Memory)

Serena는 프로젝트의 지식을 .serena/memories/에 저장할 수 있습니다.

이 프로젝트의 구성을 메모리에 남겨두면, 다음번부터 read_memory로 호출하여 문맥(context)을 빠르게 공유할 수 있습니다.

3가지 주의할 점 (Troubleshooting)

실제로 겪었던 문제들입니다.

1. 중복 등록으로 인해 시작 시 Failed to connect 발생

등록을 다시 하면 serena와 serena-mcp-server (이전 엔트리포인트)가 이중으로 남을 수 있습니다. claude mcp list에서 ✘ 표시가 나타난다면, 불필요한 쪽을 삭제합니다.

2. remove -s local이 "No MCP server"라며 실패하는 경우

claude mcp get <name>은 -s local로 삭제하라고 안내하지만, 그대로 실행하면 실패하는 경우가 있습니다. 스코프(scope) 지정을 제외하면 삭제할 수 있습니다.

claude mcp remove serena-mcp-server

이는 Claude Code 측의 알려진 동작이며, 버전에 따라 달라질 수 있습니다.

3. 글로벌 등록이 다른 프로젝트로 유출되는 경우

앞서 언급했듯이, user 스코프에 --project를 고정하여 등록하면 다른 프로젝트로 유출됩니다. 등록은 프로젝트 내에서 local 스코프로 통일합니다.

요약

• Serena는 코드를 구문(syntax)으로 이해하는 MCP 서버입니다. grep보다 정확하며 토큰을 절약합니다.
• 도입 과정은 claude mcp add를 통한 등록, claude mcp list를 통한 연결 확인, serena project index를 통한 인덱스 생성 순입니다. 기본 흐름은 overview → find_symbol → find_referencing_symbols → replace_symbol_body입니다.
• 주의할 점은 "중복 등록", "remove의 스코프", "글로벌 등록" 세 가지입니다.

Discussion