본문 바로가기
카테고리 없음

macOS M1에서 Serena MCP 설정 가이드

제이널 2026. 1. 6. 11:32

목차

  1. 사전 요구사항
  2. 단계별 설치 과정
  3. Claude Desktop 구성
  4. 프로젝트 활성화
  5. 고급 설정
  6. 유용한 명령어 모음
  7. 관련 문서

1. 사전 요구사항

필수 소프트웨어

  • macOS 11.0 이상 (M1/M2/M3 등 Apple Silicon)
  • Claude Desktop 최신 버전
  • Xcode Command Line Tools (언어 서버용)

호환성 확인

macOS M1은 uv와 Serena MCP를 완벽하게 지원합니다. Rosetta 2 변환이 필요 없습니다.

2. 단계별 설치 과정

Step 1: Xcode Command Line Tools 설치

xcode-select --install

설치가 이미 되어있다면 다음 명령으로 확인하세요:

xcode-select -p

 

Step 2: uv 패키지 매니저 설치

 

brew install uv

 

설치 확인:

uv --version
uvx --version

 

 

3. Claude Desktop 구성

Step 1: 설정 파일 찾기

Claude Desktop을 열고:

  1. File → Settings → Developer → MCP Servers → Edit Config

또는 터미널에서 직접 편집:

vi ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Serena MCP 추가

기존 설정 파일에 다음을 추가합니다:

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

 

Step 4: Claude Desktop 재시작

중요: 단순히 창을 닫는 것으로는 부족합니다. macOS에서는 창을 닫으면 백그라운드에서 계속 실행됩니다.

# Option 1: 터미널에서
killall "Claude"

# Option 2: Dock에서 우클릭 → Quit

# Option 3: Command + Q로 강제 종료

그 후 Claude Desktop을 다시 열고, Chat 인터페이스에 작은 망치(🔨) 아이콘이 나타났는지 확인하세요. 이는 Serena MCP가 성공적으로 연결되었음을 의미합니다.

4. 프로젝트 활성화

Step 1: 프로젝트 디렉토리 구성

작업할 프로젝트 폴더가 있어야 합니다:

mkdir ~/my_python_project
cd ~/my_python_project

 

Step 2: Claude Desktop에서 프로젝트 활성화

Claude Desktop을 열어서 Chat 창에 다음을 입력하세요:

Activate the project /Users/YOUR_USERNAME/my_python_project

또는 프로젝트 이름으로 (이전에 활성화한 경우):

Activate the project my_python_project

Serena가 프로젝트를 분석합니다. 첫 실행 시 온보딩 프로세스가 시작될 수 있으니, 이를 진행하도록 Claude에게 요청하세요.

 

 

Step 3: 큰 프로젝트 최적화

프로젝트가 크다면, 인덱싱을 통해 속도를 향상시킬 수 있습니다:

cd ~/my_python_project
uvx --from git+https://github.com/oraios/serena serena project index

이 명령어는 프로젝트의 코드 구조를 미리 분석하여 나중에 Serena 도구가 더 빠르게 작동하도록 합니다.

5. 고급 설정

Serena 설정 파일

Serena는 2개의 YAML 설정 파일을 사용합니다:

1. 전역 설정: ~/.serena/serena_config.yml

첫 실행 후 자동 생성됩니다. 편집하려면:

uvx --from git+https://github.com/oraios/serena serena config edit
record_tool_usage_stats: true
included_optional_tools: []

2. 프로젝트별 설정: <project>/.serena/project.yml

각 프로젝트마다 자동 생성됩니다:

read_only: false  # true로 설정하면 읽기 전용 모드
project_name: my_python_project

보안 팁: 처음에는 read_only: true로 설정한 후, 신뢰할 수 있는 프로젝트만 false로 변경하세요.

 

6. 유용한 명령어 모음

# uv 버전 확인
uv --version

# Python 버전 확인 (uv를 통한)
uv python --version

# 특정 프로젝트 인덱싱
cd ~/my_project && uvx --from git+https://github.com/oraios/serena serena project index

# Serena 대시보드 수동 접속
open http://localhost:24282/dashboard/index.html

# 설정 파일 직접 편집
nano ~/.serena/serena_config.yml
nano ~/.serena/project.yml

# Claude Desktop 로그 확인
tail -f ~/Library/Logs/Claude/claude.log

7. 관련 문서

 

티스토리툴바