😅 Serena MCP를 설치하려다 WSL까지…
Claude Code에 Serena MCP를 추가하려고 했어요. 공식 문서 보니까 명령어 하나면 끝날 것 같더라고요?
그런데… 4시간 동안 삽질하고, Claude Code까지 먹통 만들고, 결국 WSL을 설치하게 됐습니다 😅
본격적인 삽질기를 시작하기 전에, 도대체 Serena MCP가 뭐길래 이렇게까지 했는지부터 설명해드릴게요!
🤖 Serena MCP가 대체 뭐길래?
AI 코딩의 고질적인 문제
일반 AI 도구로 코딩하다 보면 이런 상황 겪어보셨을 거예요.
개발자: "이 파일 수정해줘"
AI: "이 파일만 봤어요. 수정 완료!"
결과: 다른 파일들이랑 스타일이 다름... 😅
AI가 프로젝트 전체 맥락을 이해하지 못하고, 요청한 파일만 덜렁 보고 수정하는 거죠. 마치 프로젝트를 처음 본 인턴한테 일 시키는 느낌이랄까요?
Serena MCP의 해결책
Serena는 AI가 프로젝트 전체를 이해하고 작업할 수 있게 해주는 무료 오픈소스 도구입니다. Language Server Protocol을 활용해서 코드의 의미를 파악하고, 연관된 파일들을 함께 고려해서 수정할 수 있죠.
개발자: "이 파일 수정해줘"
Serena + AI: "프로젝트 전체를 분석했고, 연관된 파일들도 체크했어요"
결과: 프로젝트 전체와 일관성 있는 수정! ✨
Serena의 핵심 기능
Serena는 다음과 같은 강력한 기능들을 제공합니다:
의미 기반 코드 검색 (Semantic Code Retrieval)
- 단순 텍스트 검색이 아니라 코드의 의미를 이해해요
- “사용자 인증 처리하는 곳 찾아줘” 하면 변수명이 달라도 관련 코드를 다 찾아냅니다
심볼 레벨 이해 (Symbol-Level Intelligence)
- 함수, 클래스, 변수 단위로 코드를 이해해요
- 어디서 사용되는지, 어떤 관계인지 파악합니다
다국어 지원
- Python, JavaScript, TypeScript, Rust, Go, Java 등 8개 이상 언어 지원
- 언어 서버가 자동으로 설치돼요
프로젝트 기억 기능
- 첫 실행 시 프로젝트를 분석하고 기억해요
- 다음에는 설명 없이도 프로젝트를 이해하고 있습니다
왜 Serena를 쓰는가?
가장 큰 이유는 무료라는 것! Cursor나 Windsurf 같은 유료 도구들은 월 $20-100 하는데, Serena는 완전 무료입니다. Claude 무료 플랜으로도 사용할 수 있고요.
실제 사용 후기를 보면:
- Sudoku 앱 UI를 개선하는데, AI가 프로젝트가 Next.js 기반 크로스 플랫폼 앱이라는 걸 이해하고, TODO 파일까지 읽어서 계획을 파악했다고 해요
- OAuth 추가 작업에서 60-70% 시간 단축, 버그도 적고 일관성 있는 코드가 생성됐다고 합니다
이 정도면… 설치할 만하죠? 😊
🔥 Windows PowerShell에서의 대삽질
자, 이제 본격적인 삽질 이야기를 시작해볼게요.
첫 번째 에러 - unknown option ‘–from’
공식 문서에 나온 명령어를 PowerShell에 복붙했어요.
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
바로 에러가 떴습니다.
error: unknown option '--from'
뭐야, --from 옵션이 없다고? 공식 문서에 나온 명령어인데?
시도 1: uv 버전이 문제인가?
“아, 내 uv가 구버전이라 --from 옵션을 모르는 거구나!” 하고 바로 업그레이드 시도했어요.
uv self update
확인해보니 이미 0.8.22 최신 버전이더라고요. 이게 아니네… 😰
시도 2: 명령어 문법을 바꿔보자
혹시 문법이 달라진 건가 싶어서 여러 가지 시도를 해봤어요.
# 이것도 해보고
uv tool run --from git+https://github.com/oraios/serena
# 저것도 해보고
uv run --with git+https://github.com/oraios/serena
# 다 안 됨...
전부 실패. 뭐가 문제인지 감도 안 잡히더라고요.
시도 3: 그럼 로컬에 클론해서?
“그냥 저장소 클론해서 로컬로 설치하면 되잖아!” 했는데… 귀찮아서 포기했어요. 공식 문서대로 안 되는데 왜 내가 우회해야 하나 싶더라고요 😤
시도 4: CMD는 어떨까?
PowerShell이 문제인가 싶어서 CMD로 갈아탔어요.
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project %CD%
오! 이번엔 설치는 됐어요! 근데…
Error: Invalid project path: $PWD
아 맞다, CMD에서는 $(pwd) 대신 %CD%를 써야 하는데 설정에는 $PWD가 그대로 들어가 있었던 거죠. 이것도 실패 😅
💥 클로드 코드까지 먹통 되다
여기까지 약 2시간 반 정도 지난 시점이에요.
이것저것 시도하다가… Claude Code가 아예 먹통이 됐어요. 명령어 입력해도 반응이 없고, 재시작해도 안 되고.
“아 이거 완전 꼬였네…”
뭔가 설정이 잘못된 건지, MCP 서버 추가하다가 꼬인 건지 모르겠지만 완전히 작동을 안 하더라고요. 심지어 claude 명령어 자체가 안 먹혔어요 😤
결국 Claude Code를 완전히 삭제하고 재설치했습니다.
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
재설치 후에는 다시 작동했지만, Serena 설치 문제는 여전히 해결 안 됨.
이때쯤 되니까 진짜 짜증이 나더라고요. 이게 뭐 하는 짓인가 싶었어요. 무료 도구 하나 깔려다가 유료 도구도 망가뜨리고… 😰
💡 그래, WSL이다!
Claude Code 재설치하고 잠시 멍때리다가 문득 생각이 들었어요.
“그냥 Linux 환경에서 하면 되잖아?”
이 생각이 든 순간, 왜 진작에 이 생각을 안 했나 싶더라고요. 어차피 제 서버는 Ubuntu인데, Windows에서 억지로 할 이유가 없었죠.
Linux에서는 명령어 파싱도 정확하고, 공식 문서의 예제도 다 Linux 기준이고. Windows에서만 이상하게 안 되는 거였어요.
WSL 설치
관리자 권한으로 PowerShell을 열고 한 줄이면 끝이에요.
wsl --install
설치가 진행되고, 재부팅하라고 나옵니다. 재부팅하면 Ubuntu가 자동으로 설치되고, 초기 사용자 계정 설정하라고 나와요.
사용자명이랑 비밀번호만 입력하면 설치 완료! 정말 간단하죠?
IntelliJ 터미널 설정 변경
저는 IntelliJ IDEA를 쓰니까 터미널 설정을 바꿔줬어요.
Settings > Tools > Terminal > Shell path를 wsl.exe -d Ubuntu로 변경.
이제 IntelliJ 터미널을 열면 바로 Ubuntu 환경이 나와요. Windows 터미널 따로 열 필요도 없고 편하더라고요 😊
🛠️ Ubuntu 환경 세팅
WSL Ubuntu가 설치됐으니 이제 필요한 도구들을 설치해야죠.
Python 설치
sudo apt update
sudo apt install python3 python3-pip python-is-python3
Ubuntu 24는 기본적으로 Python 3.12가 깔려 있지만, python 명령어를 쓰려면 python-is-python3 패키지가 필요해요. 이거 안 깔면 python3로만 실행해야 하거든요.
uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
설치 스크립트가 자동으로 경로를 설정해주는데, source ~/.bashrc로 환경변수를 리로드해줘야 바로 사용 가능해요.
Node.js 설치 (nvm 사용)
Claude Code는 Node.js가 필요하니까 nvm으로 설치했어요.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
LTS 버전이 자동으로 설치되고 활성화돼요. nvm을 쓰면 나중에 Node 버전 관리도 편하고요.
Claude Code 설치
npm install -g @anthropic-ai/claude-code
이제 준비 끝! 드디어 Serena를 설치할 차례입니다.
🎉 드디어 Serena MCP 설치 성공!
프로젝트 디렉토리로 이동해서 공식 문서 그대로 입력했어요.
cd /mnt/c/Users/사용자명/프로젝트경로
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
결과: 한 방에 성공! 🎉
4시간 동안 Windows에서 안 되던 게 Ubuntu에서는 그냥 됐어요. 공식 문서 명령어 그대로 복붙만 하면 끝이더라고요.
에러도 없고, 경고도 없고, 그냥 “Installation successful!” 이렇게 뜨는 거예요. 진짜 허무할 정도로 간단했어요 😅
🚀 Serena MCP 사용하기
설치가 끝났으면 이제 사용할 차례죠.
기본 사용법
# Claude Code 실행
claude
# MCP 서버가 disconnect 되면
/mcp
# 프로젝트 활성화
Activate the project /mnt/c/Users/사용자명/프로젝트경로
Windows 파일 시스템은 /mnt/c/ 경로로 접근할 수 있어요. C 드라이브가 /mnt/c에 마운트되어 있거든요.
처음 사용 시 - 온보딩
처음 Serena를 실행하면 온보딩 과정이 필요해요. 프로젝트를 읽고 이해하고 준비하는 과정인데, 채팅으로 “Start Serena onboarding"이라고 하면 됩니다.
이 과정에서 프로젝트 전체를 분석하고, .serena/memories 폴더에 기억을 저장해요. 다음부터는 이 기억을 바탕으로 작업하니까 훨씬 빠르고 정확하죠.
주의할 점은 온보딩에서 많은 파일을 읽기 때문에 토큰을 꽤 소비한다는 거예요. Claude 무료 플랜 쓰시는 분들은 조심하셔야 해요!
실제 사용 예시
# 코드 분석
"이 프로젝트에서 사용자 인증은 어떻게 처리하고 있어?"
# 코드 수정
"UserProfile 컴포넌트가 너무 크니까 적절히 분리해줘"
# 일관성 있는 수정
"다크모드 기능을 추가해줘"
→ Serena가 프로젝트 전체의 테마 관리 방식을 파악하고
모든 컴포넌트에 일관되게 적용해줍니다
💭 이번에 배운 것들
Windows에서 uv의 한계
Windows PowerShell이나 CMD에서는 uv의 명령어 파싱이 제대로 안 되는 것 같아요. 특히 --from 같은 옵션이 포함된 복잡한 명령어는 문제가 생기더라고요.
Linux에서는 같은 명령어가 아무 문제 없이 작동하는 걸 보면, Windows 환경 특유의 이슈인 것 같아요. 셸의 명령어 파싱 방식이 다르거나, 특수문자 처리에 차이가 있는 거겠죠.
Claude Code 먹통 해결법
Claude Code가 먹통 됐을 때는 깔끔하게 삭제하고 재설치하는 게 답이에요.
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code
설정 파일이 꼬인 경우도 있으니까 ~/.claude 폴더를 백업해두고 삭제하는 것도 방법이에요.
WSL의 위력
서버가 Linux인 개발자라면 WSL 사용을 정말 강력 추천해요. 이유는:
1. 명령어가 서버 환경과 동일
- 로컬에서 테스트한 명령어를 서버에 그대로 쓸 수 있어요
- 셸 스크립트도 동일하게 작동합니다
2. Linux 도구들을 네이티브로 사용
- apt, zsh, oh-my-zsh 등 모든 Linux 도구를 쓸 수 있어요
- Docker도 WSL에서 훨씬 빠르게 작동합니다
3. Windows 파일 시스템 접근 가능
/mnt/c로 Windows 파일을 바로 건드릴 수 있어요- Windows와 Linux 환경을 자유롭게 오갈 수 있습니다
4. IDE 통합 가능
- IntelliJ, VSCode 모두 WSL 터미널을 지원해요
- Windows에서 IDE 쓰면서 Linux 환경에서 명령어 실행 가능합니다
삽질도 경험이다
처음부터 WSL로 갔으면 30분이면 끝났을 일을 4시간 동안 했네요 😅
하지만 이 과정에서:
- Windows 환경의 한계를 알게 됐고
- Claude Code 재설치 방법도 배웠고
- WSL 세팅까지 완료했고
- Serena MCP의 가치를 더 실감하게 됐으니…
결과적으로는 나쁘지 않은 것 같아요! 여러분은 저처럼 헤매지 마시고 처음부터 WSL로 가세요 😊
🎯 마무리
Windows에서 개발 도구 설치하다가 막히면, 일단 WSL 고려해보세요. 특히:
- 서버 환경과 동일하게 작업하고 싶다면
- Linux 기반 오픈소스 도구를 쓴다면
- 명령어 호환성 문제를 겪고 있다면
WSL이 답입니다!
그리고 Serena MCP, 정말 추천해요. 무료로 Cursor나 Windsurf 수준의 AI 코딩 경험을 할 수 있다는 게 믿기지 않을 정도예요. 프로젝트 전체를 이해하는 AI와 함께 코딩하는 경험, 한 번 해보시면 절대 돌아갈 수 없어요!
혹시 비슷한 문제 겪으신 분 있으신가요? 댓글로 경험 공유해주세요! 😊
다음 포스트 예고: WSL에서 개발 환경 완전 세팅하기 (zsh + oh-my-zsh + 플러그인까지!)
댓글