[AI] serena MCP 개념 및 설치 방법

serena MCP란?

• Serena MCP(Model Context Protocol) 서버는 Oraios AI에서 개발 및 제공하는 오픈 소스 코딩 에이전트 툴킷
• LSP(Language Server Protocol)을 활용하여 분석함
• LSP는 원래 VSCode나 Xcode 같은 IDE가 언어별(Python, Go, TS 등) 분석 엔진과 소통하기 위해 만든 표준 규격
  • 구문 분석: 단순 텍스트가 아니라 Class, Method, Variable 간의 관계를 트리 구조로 이해
  • 심볼 추적: find_symbol을 통해 특정 함수가 정의된 위치와 사용된 위치(References)를 즉시 찾아냄
  • 효율적인 컨텍스트: 수만 줄의 코드 중 LLM이 정말로 수정해야 할 정확한 지점만 집어내어 전달
  • 전체 파일을 읽거나 `grep`과 같은 텍스트 기반 검색에 의존하는 대신, `find_symbol`이나 `insert_after_symbol`과 같은 정교한 도구를 사용하여 복잡한 프로젝트에서도 정확한 컨텍스트를 찾고 코드를 수정

serena 설치

• uv 설치

brew install uv

• serena 적용

# 프로젝트 디렉토리 이동
cd ~/work

# Serena 클론
git clone https://github.com/oraios/serena
cd serena

# serena 폴더 추가
mkdir -p ~/.serena

# 설정 파일 복사
cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml

클로드코드와 통합

• mcp 서버 설정 (아래 명령어 입력 시 .claude.json에 자동으로 입력됨)

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

• 위에 까지 입력하고 ~/.serena.json 파일 확인
  • 아래처럼 serena가 동일한 내용으로 채워져 있지 않다면 serena json부분을 지우고 다시 위 명령어를 실행

"mcpServers": {
  "serena": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/oraios/serena",
      "serena-mcp-server",
      "--context",
      "ide-assistant",
      "--project",
      "/Users/jake/Desktop/cobot"
    ],
    "env": {}
  }
},

• mcp 서버 띄우기

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

• claude 코드 챗에 들어가서 /mcp 입력하여 연결된 것 확인

serena 관련 파일

• 프로젝트 루트에 생성된 .serena 폴더에 가면 아래와 같은 폴더와 파일이 생성됨 (이 부분은 클로드코드를 사용할때 자동으로 업데이트됨)
  • cache: LSP 기반의 코드 심볼 및 인덱싱 정보를 임시 저장하여 분석 속도를 높이는 공간
  • memories: 프로젝트의 고유 규칙, 아키텍처 맥락 등 AI가 학습한 장기 지식을 보관하는 곳
  • project.yml: 관리 중인 프로젝트의 경로, 상태, 메타데이터를 기록한 통합 명세서 파일

 

 

* 참고

https://github.com/oraios/serena