Serena MCP

개요

Serena는 SEmantic Retrieval & Editing Noetic Agent의 약자. 파일 전체를 통째로 읽지 않고 의미론적(semantic) 방식으로 필요한 코드·내용만 정확히 찾아주는 MCP 서버. 불필요한 파일 읽기로 인한 토큰 낭비를 대폭 줄여줌.

• GitHub: https://github.com/oraios/serena
• 설치: uvx 기반 (pip 불필요)
• 용도: Claude Code, Cursor 등 MCP 지원 AI 에이전트와 연동

---

핵심 기능

기능	설명
시맨틱 파일 탐색	전체 파일 읽기 없이 의미 기반 검색
파일 찾기	프로젝트 내 파일 위치 파악
디렉토리 나열	구조 파악
패턴 검색	코드 패턴·심볼 기반 탐색
토큰 절약	필요한 부분만 읽어 컨텍스트 낭비 방지

---

설치 & 설정

사전 조건

# uvx 설치 (uv 패키지 매니저)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 또는
pip install uv

Claude Desktop / Claude Code 설정

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

macOS: /opt/homebrew/bin/uvx Linux: uvx 또는 ~/.local/bin/uvx

Linux 설정 예시

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

---

작동 방식

기존 방식:
  AI → 파일 전체 읽기 → 필요한 부분 파악 → 토큰 낭비 ❌

Serena 방식:
  AI → Serena MCP → 의미 기반 인덱싱 → 필요한 코드 조각만 반환 ✅

• 프로젝트 코드베이스를 심볼·구조 단위로 인덱싱
• 함수, 클래스, 변수 등 심볼 기반으로 정확히 탐색
• 대형 프로젝트에서 효과 극대화

---

주요 MCP 도구 목록

도구	설명
find_file	이름/패턴으로 파일 찾기
list_dir	디렉토리 구조 탐색
search_symbol	코드 심볼(함수·클래스) 검색
get_symbol	특정 심볼의 코드만 추출
search_pattern	정규식·패턴 검색

---

효과

• 토큰 절약: 대형 코드베이스에서 수천 토큰 절감
• 속도 향상: 필요한 컨텍스트만 로드
• 정확도: 의미 기반 검색으로 관련 코드 정확 파악
• 비용 절감: API 호출 비용 감소

---

관련 항목

• Claude Code CLI
• Claude Code 토큰 절약
• MCP (Model Context Protocol)
• Cursor