🧩 Model Context Protocol (MCP) & Serena MCP 정리

1. MCP란?

MCP (Model Context Protocol) 은 Anthropic(Claude 개발사)이 제안한
AI 모델과 외부 리소스(파일, DB, API 등)가 표준화된 방식으로 상호작용하도록 하는 오픈 프로토콜이다.

💡 핵심 목적

• AI 모델이 외부 시스템의 데이터를 안전하고 일관된 방식으로 접근할 수 있게 함
• 기존의 “커스텀 플러그인/툴 연결 문제(N×M)”를 하나의 통합 인터페이스로 단순화

🧠 주요 특징

| 항목 | 설명 | |——|——| | 통신 방식 | JSON-RPC 2.0 기반 양방향 통신 | | 구조 | 클라이언트(모델) ↔ MCP 서버(리소스 제공자) | | 보안 | 명시적 권한 요청 / 승인 기반 접근 | | 활용 범위 | 파일 읽기, API 호출, 데이터 조회, 코드베이스 분석 등 |

---

2. MCP의 기본 구조

+----------------+
| Claude / LLM   |  ← 클라이언트
+--------+-------+
|
|  JSON-RPC 요청 (MCP 프로토콜)
↓
+--------+-------+
| MCP Server     |  ← 외부 리소스 접근 서버
| (예: Serena)   |
+--------+-------+
|
↓
+----------------+
| Files / DB / APIs |
+----------------+

---

3. Serena MCP란?

Serena MCP는 MCP 표준을 구현한 코드베이스 분석용 서버이다.
Claude Code 또는 Claude Desktop 등과 연동되어,
AI가 프로젝트의 전체 코드를 구조적으로 이해할 수 있게 돕는다.

🧰 Serena MCP의 역할

| 기능 | 설명 | |——|——| | 코드 인덱싱 | 프로젝트 전체 파일을 스캔하고, 함수/클래스 관계를 데이터베이스화 | | 참조 추적 | 함수 호출 관계, 클래스 상속, 변수 참조 등을 추적 | | 빠른 검색 | Claude의 요청에 맞춰 관련 코드나 파일을 즉시 반환 | | 문맥 관리 | 대규모 코드에서 모델이 처리 가능한 범위를 관리 | | MCP 통신 | Claude와 JSON-RPC로 명령/응답 처리 |

---

4. Claude Code + Serena MCP 연결 흐름

사용자 요청
↓
Claude Code (클라이언트)
↓
[MCP 요청]
↓
Serena MCP (서버)
↓
코드베이스 / 파일 시스템

예를 들어 사용자가 다음과 같이 묻는다면:

“UserService 클래스가 어디서 사용되나요?”

1. Claude Code가 MCP 요청을 보냄
2. Serena MCP가 코드베이스를 탐색
3. 호출 위치를 찾아 JSON 응답
4. Claude Code가 자연어로 결과를 요약하여 사용자에게 보여줌

---

5. Serena MCP 설치 요약 (예시)

# 1️⃣ 저장소 클론
git clone https://github.com/oraios/serena
cd serena

# 2️⃣ 의존성 설치 (uv 사용)
uv sync

# 3️⃣ MCP 서버 실행
uv run --directory /path/to/serena serena-mcp-server --context ide-assistant

# 4️⃣ Claude Code에 서버 등록
claude mcp add serena -- \
  uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant

⚙️ 설정 파일: ~/.serena/serena_config.yml

web_dashboard: false
read_only: true

---

6. Claude ↔ Serena 연동 설정

🧩 전역 설정 (권장)

Claude Desktop은 MCP 서버 목록을 전역 파일(servers.json)로 관리한다.

Mac 예시 경로:

~/Library/Application Support/Claude/servers.json

Linux 예시 경로:

~/.config/Claude/servers.json

✍️ 예시 설정

{
  "servers": [
    {
      "id": "serena",
      "name": "Serena MCP Server",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/serena", "serena", "start-mcp-server"],
      "env": {},
      "autoStart": true
    }
  ]
}

Claude를 재시작하면 자동으로 Serena MCP 서버를 감지하고 연결한다.

“Serena MCP Server connected” 메시지가 표시되면 성공 🎉

---

7. 고급 설정 (선택 사항)

🧠 여러 프로젝트에서 다른 Serena 인스턴스 사용하기

기본적으로 servers.json은 전역 설정이지만, 서로 다른 프로젝트별로 다른 Serena 서버를 등록할 수도 있다.

예시

{
  "servers": [
    {
      "id": "serena-dev",
      "name": "Serena (Dev)",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/dev/serena", "serena", "start-mcp-server"]
    },
    {
      "id": "serena-prod",
      "name": "Serena (Prod)",
      "command": "uv",
      "args": ["run", "--directory", "/Users/you/prod/serena", "serena", "start-mcp-server"]
    }
  ]
}

또는 환경변수 기반으로도 지정 가능하다.

{
  "servers": [
    {
      "id": "serena",
      "name": "Serena (Dynamic)",
      "command": "uv",
      "args": ["run", "--directory", "$SERENA_PATH", "serena", "start-mcp-server"]
    }
  ]
}

# 프로젝트별로 환경변수 설정 후 실행
export SERENA_PATH=/Users/you/myproject/serena
claude &

---

8. 장점 및 주의사항

✅ 장점

• 코드 이해력 향상 (함수 관계, 호출 추적 등)
• 대규모 프로젝트 탐색 속도 개선
• Claude Code의 맥락 품질 향상
• uv 기반 설치로 빠르고 가벼움
• Claude와 자동 통신 (MCP 프로토콜 표준)

⚠️ 주의사항

• 프로젝트에 접근 권한이 있는 경우에만 실행
• read_only 모드 권장 (코드 수정 방지)
• servers.json은 전역 적용이므로, 잘못된 경로 설정 시 Claude 전체에서 에러 발생

---

9. 요약

구분	설명
MCP	모델이 외부 리소스와 통신하기 위한 오픈 프로토콜
Serena MCP	코드베이스 구조를 Claude에 제공하는 MCP 서버
Claude Code	사용자 명령을 이해하고 Serena MCP로부터 데이터 요청
핵심 장점	코드 탐색·리팩토링·맥락 이해 향상
필수 조건	Python + uv 환경, 로컬 서버 실행 권한
연결 방식	Claude ↔ Serena 간 JSON-RPC 기반 양방향 통신
설정 위치	전역: servers.json / 로컬: ~/.serena/config.yml

---

✨ 한마디로 MCP는 “AI 모델을 외부 리소스와 연결하는 표준 인터페이스”이고, Serena MCP는 그 표준을 활용해 Claude가 “코드베이스를 이해하고 탐색할 수 있게 돕는 로컬 도구 서버”이다.