Claude Code 토큰 절약 시리즈 ① Serena MCP - 의미 기반 검색으로 토큰 폭발 막기

이 글에서 다루는 내용

이 글은 Claude Code 토큰 절약 시리즈의 첫 편입니다. 가장 효과가 즉시 체감되는 도구인 Serena MCP를 다룹니다. Serena는 oraios 팀이 만든 오픈소스 MCP 서버로, 코드 베이스를 LSP(Language Server Protocol) 기반으로 다뤄 심볼 단위 의미 검색을 제공합니다. grep과 전체 파일 읽기를 대체해 같은 작업을 훨씬 적은 토큰으로 끝낼 수 있습니다. 이 글은 토큰이 빠지는 진짜 이유부터 Serena의 핵심 도구, UV 기반 설치, Claude Code 등록, 첫 프로젝트 온보딩, 그리고 토큰 절감이 일어나는 메커니즘까지 단계별로 정리합니다. 기준 시점은 2026년 5월입니다.

---

1. 토큰이 빠지는 진짜 이유 - grep과 전체 파일 읽기

Claude Code가 코드 작업을 시작하면 가장 먼저 하는 일은 코드를 찾는 것입니다. 기본 도구는 Grep과 Read인데, 이 두 도구의 한계가 토큰 폭발의 직접 원인입니다.

• grep은 텍스트 매칭입니다. getUserById를 검색하면 정의·호출·주석·문서·테스트가 모두 결과로 잡히고, 일부 파일은 통째로 컨텍스트에 들어갑니다.
• 전체 파일 읽기는 더 큽니다. 한 함수를 고치고 싶을 뿐인데도 LLM이 파일 전체를 읽는 게 흔하고, 이 입력 토큰이 누적되면 한도가 빠르게 소진됩니다.
• 결과적으로 LLM은 "검색 결과 노이즈"로 가득 찬 컨텍스트로 추론하게 되어, 토큰이 두 배 들면서도 답변 정확도는 더 떨어지는 악순환이 생깁니다.

50K LOC 이상의 중간 규모 저장소부터 이 문제가 본격적으로 드러납니다. Serena가 1순위 토큰 절약 도구로 꼽히는 이유가 여기에 있습니다 — 검색 단계에서 발생하는 토큰 낭비를 구조적으로 차단하기 때문입니다.

---

2. Serena MCP의 정체 - LSP 기반 의미 검색

Serena는 Language Server Protocol(LSP)을 백엔드로 사용해, 텍스트 매칭이 아니라 코드의 구조를 이해합니다. LSP는 IDE가 코드 자동 완성·정의로 점프·참조 찾기를 지원할 때 쓰는 표준 프로토콜로, VS Code·JetBrains·Vim 같은 IDE가 같은 메커니즘을 씁니다.

30개 이상의 언어를 지원합니다 — Python, JavaScript, TypeScript, Java, Rust, Go, C++, C#, Ruby, PHP, Kotlin, Swift 등 주류 언어는 거의 모두 포함됩니다.

핵심 차이는 한 줄로 정리됩니다.

"파일을 읽고 grep으로 찾는 LLM" 대신 "IDE처럼 심볼 단위로 코드를 다루는 LLM"을 만든다.

---

3. 핵심 도구들 - 심볼 단위로 일하는 4가지 명령

Serena가 Claude Code에 추가하는 도구 중 가장 자주 쓰이는 네 가지입니다.

도구	역할	대체 대상
find_symbol	함수·클래스·변수의 정의 위치를 정확히 찾음	grep + 파일 읽기
find_referencing_symbols	해당 심볼을 참조하는 모든 위치 (False Positive 0)	grep -r
replace_symbol_body	함수·메서드 본문 전체를 새 코드로 교체	파일 부분 편집 (잘못 잘릴 위험)
insert_after_symbol	특정 심볼 뒤에 새 코드 삽입	라인 기반 추가

예를 들어 "getUserById를 호출하는 모든 곳을 새 시그니처로 바꿔 줘"라는 작업이 들어오면, 기존 도구 흐름은 grep으로 후보를 모은 뒤 파일들을 읽어 컨텍스트에 넣고 LLM이 직접 편집을 시도하는 방식입니다. Serena 흐름은 find_referencing_symbols로 정확한 호출 위치만 받고 LSP가 원자적으로 편집을 처리합니다 — 같은 작업이 토큰의 일부만으로 끝납니다.

---

4. 사전 준비 - UV 패키지 매니저

Serena는 Python 환경 위에서 동작하고, 공식적으로 UV(uvx) 패키지 매니저 사용을 권장합니다. UV는 Astral 팀이 만든 차세대 Python 도구로, pip보다 훨씬 빠르고 가상 환경 관리도 자동입니다.

아직 UV가 없다면 한 줄로 설치합니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 새 셸에서 버전을 확인합니다.

uvx --version

⚠️ pip로 직접 Serena를 설치하지 말 것. 공식 README에서도 MCP 마켓플레이스나 plugin marketplace 등록본은 오래된 설치 명령을 쓰는 경우가 있어 권장하지 않는다고 명시합니다.

---

5. Claude Code에 Serena 등록하기

등록은 한 줄입니다. 작업할 프로젝트 루트로 이동한 뒤 다음 명령을 실행합니다.

cd /path/to/your/project
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

옵션이 길어 보이지만 의미는 단순합니다.

• uvx --from git+... — UV가 깃허브에서 Serena를 자동 설치·실행
• --context ide-assistant — Claude Code가 이미 갖고 있는 도구와 중복되는 부분을 끄고 심볼 검색 도구만 노출
• --project $(pwd) — 현재 디렉토리를 프로젝트로 지정

등록이 끝나면 Claude Code 안에서 /mcp 명령으로 연결 상태를 확인합니다.

/mcp

출력에 serena가 connected 상태로 보이면 정상입니다.

---

6. 첫 실행 - 프로젝트 온보딩

Serena를 처음 등록한 뒤 Claude Code에 다음과 같이 던지면 자동 온보딩이 시작됩니다.

이 프로젝트의 구조를 Serena로 파악해 줘.

Serena는 다음 작업을 자동으로 수행합니다.

1. 프로젝트 디렉토리에 .serena/project.yml 생성 — 언어 자동 감지, 인덱싱 설정 저장
2. 해당 언어의 LSP를 백그라운드에서 시작 (Python이면 pyright, TS면 typescript-language-server 등)
3. 주요 진입점·테스트 위치·빌드 명령을 식별해 .serena/memories/에 메모리로 저장

이 단계가 끝나면 find_symbol·find_referencing_symbols가 즉시 동작합니다. 큰 저장소는 첫 인덱싱에 1~3분 정도 걸리지만 한 번만 하면 됩니다.

---

7. 토큰 절감의 메커니즘 - 가설 검증

"왜 절감되는가"를 막연한 주장이 아니라 구조 차이로 따져 보면 명확합니다. 같은 작업을 두 가지 흐름으로 처리할 때 입력 토큰이 어디서 발생하는지 비교합니다.

예시 작업: "UserService 클래스의 getUserById 메서드를 모든 호출 위치에서 새 시그니처로 바꿔 줘."

단계	기존 흐름 (grep + Read)	Serena 흐름
정의 찾기	grep으로 매칭 30건 → 파일 5개 통째로 읽기	find_symbol → 정의 위치 1건만 반환
호출 위치 모으기	grep -r → 호출·주석·문서·테스트 모두 매칭	find_referencing_symbols → 실제 호출만 정확히
편집 적용	파일별 부분 편집, 매번 파일 재읽기	replace_symbol_body가 LSP로 원자 편집

입력 토큰의 출처가 다른 것이 핵심입니다. 기존 흐름은 "정확한 위치를 찾기 위해 일단 다 읽는" 패턴이라 토큰이 N×파일 크기로 비례합니다. Serena 흐름은 LSP가 정답을 미리 알고 있어 위치 정보만 반환하므로 입력 토큰이 거의 일정합니다.

여기에 부수 효과가 따라옵니다. False Positive가 사라지므로 LLM이 잘못된 곳을 고치려다 실수하는 비율이 감소하고, 결과적으로 토큰 절감과 정확도 향상이 동시에 일어납니다.

---

8. 자주 막히는 단계와 해결

문제 1: /mcp에 serena가 connected로 안 뜬다

등록 명령을 프로젝트 루트가 아닌 곳에서 실행했을 가능성이 높습니다. $(pwd)가 잘못된 경로로 잡힌 것이라, 일단 등록을 제거하고 프로젝트 루트로 이동해 다시 등록합니다.

claude mcp remove serena
cd /path/to/your/project
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

문제 2: 온보딩이 너무 오래 걸린다

대형 모노레포에서는 LSP 인덱싱이 5분 이상 걸리기도 합니다. 작업할 디렉토리만 지정하면 빠릅니다.

cd /path/to/monorepo/apps/web
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

문제 3: 언어 자동 감지가 잘못됐다

여러 언어가 섞인 프로젝트에서 가끔 발생합니다. .serena/project.yml의 language 필드를 직접 지정해 주면 해결됩니다.

문제 4: Claude Desktop에서 쓰고 싶다

Claude Desktop은 claude_desktop_config.json을 직접 편집합니다. 위치는 macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json입니다.

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "desktop-app"
      ]
    }
  }
}

편집 후 Claude Desktop을 완전히 재시작합니다(트레이까지 종료).

---

마무리

Serena MCP가 1순위 토큰 절약 도구로 꼽히는 이유는, 토큰이 빠지는 가장 큰 원인인 "검색을 위해 일단 다 읽는 패턴"을 구조적으로 차단하기 때문입니다. LSP라는 검증된 표준 위에서 동작하고, Claude Code 등록은 한 줄, 30+ 언어 지원, 첫 온보딩 1~3분이면 끝입니다. 작은 사이드 프로젝트보다 50K LOC 이상의 중간 규모 저장소부터 효과가 즉시 체감되니, 가장 무거운 저장소부터 적용해 보시기를 권합니다.

다음 편에서는 두 번째 도구 — Session Report로 보는 프롬프트 캐싱의 진짜 효과를 다룹니다. Serena가 "검색 토큰"을 줄여 준다면, Session Report는 "반복 토큰"이 어디서 새는지 시각적으로 보여 줍니다.

• Serena GitHub: github.com/oraios/serena
• Serena 공식 문서: oraios.github.io/serena
• UV 설치: docs.astral.sh/uv
• MCP 표준 문서: modelcontextprotocol.io

관련 글

함께 읽으면 좋은 글

• 클로드 토큰 절약 방법 - 비용 레버 8가지
• Claude Code 설치 및 활용 완벽 가이드