Serena MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

언어 서버 지원 의미 검색 — 기호 찾기, 참조, 유형 계층 구조
기호 편집 - 본문 교체, 안전 삭제, 기호 앞/뒤 삽입
LSP를 통한 40개 이상의 언어(Python, TS/JS, Rust, Go, Java, C#, Ruby, …)
파일 간 리팩터링 — 이름 바꾸기, 파일/디렉터리 이동, 인라인, 데드 코드 제거
에이전트 세션 전반에 걸친 영구 메모리(프로젝트별)
무료 및 로컬 — 호스팅 API 없음, 토큰당 수수료 없음

라이브 데모

실제 사용 모습

serena.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "serena",
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "serena": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "serena-agent",
          "serena",
          "start-mcp-server",
          "--context=claude-desktop"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add serena -- uvx --from serena-agent serena start-mcp-server --context=claude-desktop

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Serena

1M 라인 코드베이스에서 함수의 모든 호출자를 찾습니다.

👤 성숙한 대규모 저장소에서 일하는 엔지니어 ⏱ ~10 min intermediate

언제 쓸까: 완전하고 정확한 호출자 목록이 필요합니다. grep은 거짓 긍정(주석, 문자열, 다른 범위의 비슷한 이름의 함수)을 제공하고 오버로드를 놓칩니다.

사전 조건

UV 설치 — 컬 -LsSf https://astral.sh/uv/install.sh | 쉿
Serena의 LSP가 지원하는 언어로 열린 프로젝트 — 대부분의 주류 언어는 즉시 사용 가능

흐름

프로젝트 열기

Serena로 /abs/path/to/repo를 엽니다. LSP 인덱스가 구축되었는지 확인합니다.✓ 복사됨

→ Serena는 로드된 프로젝트 루트와 LSP를 보고합니다.
기호 참조 찾기

PaymentService.chargeCustomer의 모든 통화 사이트를 찾으십시오. 오버로드 및 재정의를 포함하고 테스트를 제외합니다.✓ 복사됨

→ 정확한 파일:줄 목록, 주석/문자열에서 거짓 긍정 없음
영향 요약

호출 사이트를 모듈별로 그룹화합니다. 각 그룹에 대해 호출자가 반환 값으로 무엇을 하는지 알려주세요.✓ 복사됨

→ 단순 목록이 아닌 모듈 그룹 내러티브

결과: 변경 사항을 만지기 전에 무엇에 영향을 미칠지 정확히 알 수 있습니다.

함정

일부 다중 언어 저장소에는 여러 LSP가 필요합니다. — 언어가 서버를 공유하지 않는 경우 하위 프로젝트별로 Serena를 시작하십시오.

함께 쓰기: filesystem · github

종속 항목을 손상시키지 않고 공개 API 기호 이름 바꾸기

👤 라이브러리/프레임워크 관리자 ⏱ ~15 min intermediate

언제 쓸까: 파일 외부에서 사용될 수 있는 함수나 클래스의 이름을 바꾸는 중입니다. 텍스트 바꾸기가 아닌 LSP에 맞는 정확한 이름 바꾸기가 필요합니다.

사전 조건

Git 트리 청소 — git status clean을 통해 커밋하기 전에 diff를 검토할 수 있습니다.

흐름

이름 바꾸기 연습 실행

src/api/users.ts에서 getUser의 이름을 fetchUserById로 바꿉니다. Serena의 상징적 이름 변경을 사용하세요. 차이점을 미리 보세요. 아직 적용하지 마세요.✓ 복사됨

→ 영향을 받는 모든 파일에 대한 미리보기 비교
검토 및 신청

이름 변경을 적용합니다. Serena가 모호하다고 표시된 파일을 알려주십시오.✓ 복사됨

→ 이름 바꾸기 적용됨, 모호성 목록(있는 경우)
제품군 실행

이전 이름을 참조하는 항목에 초점을 맞춰 테스트를 실행하고 실패를 보고합니다.✓ 복사됨

→ 녹색 테스트 또는 정확한 실패 목록

결과: 이름 바꾸기는 공개 재수출, index.ts 배럴 및 오래된 JSDoc 참조를 포함하여 저장소 전체에서 깨끗합니다.

함정

LSP 이름 변경으로 동적 액세스(obj['getUser'])가 포착되지 않습니다. — 기호 이름 변경 후 이전 이름 문자열에 대해 grep을 한 번 수행합니다. Serena는 정적으로 해결할 수 없는 모든 것을 표면화합니다.

함께 쓰기: filesystem · git

주변 코드를 방해하지 않고 함수 본문 교체

👤 대용량 파일 내에서 외과적 편집을 수행하는 엔지니어 ⏱ ~10 min intermediate

언제 쓸까: 'calculatePrice' 구현을 다시 작성하고 싶지만 해당 서명과 JSDoc은 정확하게 유지됩니다. 전체 파일 재생성은 잘못된 도구입니다.

흐름

기호를 대상으로

src/billing/pricing.ts에서 calculatePrice를 찾습니다. 현재 본문만 표시합니다(서명이나 문서는 표시하지 않음).✓ 복사됨

→ 본문 전용 스니펫
본체를 교체하세요

본체만 면세 케이스를 처리하는 버전으로 교체합니다. 서명과 JSDoc을 그대로 유지합니다.✓ 복사됨

→ Serena의 본문 교체 도구가 사용됩니다. diff에서 서명이 변경되지 않음

결과: 최소한의 검토 가능한 diff — 부수적인 공백/서식 변동이 없습니다.

함정

에이전트가 전체 파일 쓰기로 대체됩니다. — 'write_file이 아닌 Serena의 기호 대체 사용'을 명시적으로 지시합니다.

함께 쓰기: filesystem

한 시간 안에 익숙하지 않은 코드베이스에 온보딩

👤 신규 고용자, 계약자 또는 OSS 기여자 ⏱ ~60 min beginner

언제 쓸까: 방금 500개 파일 저장소를 복제했으며 기여하려면 정신 지도가 필요합니다.

흐름

아키텍처 얻기

Serena와 함께 이 저장소를 엽니다. 맵을 구축합니다: 최상위 모듈, 공개 내보내기 및 기본 진입점. Serena 메모리에 'arch_overview'로 저장합니다.✓ 복사됨

→ 구조화된 개요 메모리 노트가 생성되었습니다
사용자 요청 따르기

사용자가 POST /orders를 누를 때 무슨 일이 일어나는지 추적하세요. 모든 파일을 순서대로 살펴보세요.✓ 복사됨

→ 요청 → 핸들러 → 서비스 → repo 트레일(Serena의 참조 조회 포함)
문제를 참고하세요

특이해 보이는 패턴(맞춤 데코레이터, 매직 상수)을 메모리에 'gotchas'로 저장하세요.✓ 복사됨

→ 다음 세션을 위해 저장된 메모리 메모

결과: 다음 세션에서 Claude는 이미 지도를 알고 있으므로 재가입 비용이 없습니다.

함께 쓰기: filesystem · github

조합

다른 MCP와 조합해 10배 효율

serena + filesystem

기호 인식 탐색을 위한 Serena + 임의 I/O를 위한 파일 시스템

Serena를 사용하여 인증 모듈을 찾은 다음 파일 시스템을 사용하여 해당 폴더에 대한 새 README를 작성합니다.✓ 복사됨

serena + github

Serena를 사용하여 로컬로 리팩토링합니다. 분기를 푸시하고 GitHub MCP를 통해 PR을 엽니다.

Serena를 사용하여 ApiClient → HttpClient의 이름을 바꾼 다음 'refactor(api): rename ApiClient'라는 제목의 PR을 엽니다.✓ 복사됨

serena + git

커밋하기 전에 Serena가 생성한 차이점을 검토하세요.

Serena의 이름 변경 후 git diff를 보여주세요. 의심스러운 것이 있으면 범하기 전에 신고하세요.✓ 복사됨

serena + context7

라이브러리 인식 리팩터링 — 로컬 이동을 위한 Serena, v-next API 일치를 위한 Context7

이 파일을 Next.js 15개 패턴으로 마이그레이션하세요. 새로운 API에 Context7을 사용하고 Serena를 사용하여 변경 사항을 기호적으로 적용합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
find_symbol	name: str, scope?: str	LSP 정밀도로 이름으로 클래스/함수/변수 찾기	free (local)
find_references	symbol: ref	기호의 모든 호출자/사용법 grep보다 훨씬 낫습니다.	free
get_symbols_overview	path: str	무엇을 읽을지 결정하기 전 파일/모듈 개요	free
rename_symbol	symbol: ref, new_name: str, dryRun?: bool	전체 프로젝트에서 안전한 이름 바꾸기	free
replace_symbol_body	symbol: ref, new_body: str	서명을 건드리지 않고 함수/메서드 본문을 제자리에서 교체합니다.	free
insert_before_symbol / insert_after_symbol	symbol: ref, code: str	AST 노드에 고정된 데코레이터, 가져오기 또는 형제 선언 추가	free
move_file / move_dir	src: str, dst: str	코드를 재배치하고 LSP가 모든 임포터를 수정하도록 합니다.	free
write_memory / read_memory	key: str, value?: str	세션 전반에 걸쳐 프로젝트 컨텍스트(아키텍처 맵, 문제) 유지	free
search_pattern	regex: str, path: str	대상이 명명된 기호(문자열 리터럴, 패턴)가 아닌 경우 대체	free

비용 및 제한

운영 비용

API 쿼터: 없음 - 로컬 LSP
호출당 토큰: Small — Serena는 전체 파일이 아닌 기호 범위의 조각을 반환합니다.
금액: 무료
팁: 대용량 파일에서는 read_text_file보다 get_symbols_overview + find_symbol을 선호합니다. 토큰을 10배 적게 사용하고 더 나은 신호를 얻을 수 있습니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: 없음 — 모든 것이 로컬에서 실행됩니다.

데이터 외부 송신: 기본적으로 없음. Serena는 쉘 명령을 실행할 수 있습니다(비활성화). Claude에 쓰기 액세스 권한을 부여하기 전에 도구 목록을 검토하세요.

절대 부여 금지: Access to directories outside your project

Serena는 관련 도구를 활성화하면 셸 명령을 실행할 수 있습니다. 이것을 홈 디렉토리 루트가 아닌 범위가 지정된 프로젝트 루트와 쌍으로 연결하십시오.
메모리 노트는 프로젝트 아래의 디스크에 기록됩니다. Serena 메모리에 비밀을 저장하지 마십시오. 일반 텍스트입니다.

문제 해결

자주 발생하는 오류와 해결

LSP 시작 실패 / 기호 없음

프로젝트 언어에 맞는 언어 서버가 설치되어 있는지 확인하세요(예: Python의 경우 pyright, TS의 경우 typescript-언어-서버). Serena는 사용 중인 LSP 목록을 기록합니다.

확인: Run Serena in verbose mode; confirm LSP handshake succeeded

이름 바꾸기에서 일부 파일을 건너뛰었습니다.

일반적으로 파일이 LSP의 작업 공간에 없음을 의미합니다. 프로젝트 루트가 하위 패키지가 아닌 모노레포 루트인지 확인하세요.

확인: Ask Serena to list its workspace roots

에이전트는 Serena 도구 대신 원시 파일 쓰기로 대체됩니다.

CLAUDE.md에 명시적인 규칙을 추가하세요. '기호 연산의 경우 항상 Serena의 도구를 사용하세요. 기존 .py/.ts 파일에 write_file을 사용하지 마세요'

확인: Re-run the task; inspect tool_use calls in the trace

uvx: 명령을 찾을 수 없습니다

먼저 uv를 설치하십시오: 컬 -LsSf https://astral.sh/uv/install.sh | 쉿; 그런 다음 터미널을 다시여십시오

확인: uvx --version

대안

Serena 다른 것과 비교

대안	언제 쓰나	단점/장점
JetBrains MCP	이미 JetBrains IDE에 거주하고 있으며 에이전트가 리팩터링 도구를 구동하기를 원합니다.	개방형 IDE 프로세스가 필요합니다. 더 무겁다
filesystem	기호 인식은 필요하지 않습니다. 파일 읽기/쓰기만 하면 됩니다.	의미 검색 또는 안전한 이름 변경 없음
mcp-language-server	Serena의 메모리 + 쉘 레이어가 아닌 더 작은 LSP 전용 래퍼를 원합니다.	더 적은 수준의 도구; 워크플로를 직접 구성합니다.

Serena

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Serena

1M 라인 코드베이스에서 함수의 모든 호출자를 찾습니다.

사전 조건

흐름

함정

종속 항목을 손상시키지 않고 공개 API 기호 이름 바꾸기

사전 조건

흐름

함정

주변 코드를 방해하지 않고 함수 본문 교체

흐름

함정

한 시간 안에 익숙하지 않은 코드베이스에 온보딩

흐름

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Serena 다른 것과 비교

더 보기

리소스