😅 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에 복붙했어요.
| |
바로 에러가 떴습니다.
error: unknown option '--from'
뭐야, --from 옵션이 없다고? 공식 문서에 나온 명령어인데?
시도 1: uv 버전이 문제인가?#
“아, 내 uv가 구버전이라 --from 옵션을 모르는 거구나!” 하고 바로 업그레이드 시도했어요.
| |
확인해보니 이미 0.8.22 최신 버전이더라고요. 이게 아니네… 😰
시도 2: 명령어 문법을 바꿔보자#
혹시 문법이 달라진 건가 싶어서 여러 가지 시도를 해봤어요.
| |
전부 실패. 뭐가 문제인지 감도 안 잡히더라고요.
시도 3: 그럼 로컬에 클론해서?#
“그냥 저장소 클론해서 로컬로 설치하면 되잖아!” 했는데… 귀찮아서 포기했어요. 공식 문서대로 안 되는데 왜 내가 우회해야 하나 싶더라고요 😤
시도 4: CMD는 어떨까?#
PowerShell이 문제인가 싶어서 CMD로 갈아탔어요.
| |
오! 이번엔 설치는 됐어요! 근데…
Error: Invalid project path: $PWD
아 맞다, CMD에서는 $(pwd) 대신 %CD%를 써야 하는데 설정에는 $PWD가 그대로 들어가 있었던 거죠. 이것도 실패 😅
💥 클로드 코드까지 먹통 되다#
여기까지 약 2시간 반 정도 지난 시점이에요.
이것저것 시도하다가… Claude Code가 아예 먹통이 됐어요. 명령어 입력해도 반응이 없고, 재시작해도 안 되고.
“아 이거 완전 꼬였네…”
뭔가 설정이 잘못된 건지, MCP 서버 추가하다가 꼬인 건지 모르겠지만 완전히 작동을 안 하더라고요. 심지어 claude 명령어 자체가 안 먹혔어요 😤
결국 Claude Code를 완전히 삭제하고 재설치했습니다.
| |
재설치 후에는 다시 작동했지만, Serena 설치 문제는 여전히 해결 안 됨.
이때쯤 되니까 진짜 짜증이 나더라고요. 이게 뭐 하는 짓인가 싶었어요. 무료 도구 하나 깔려다가 유료 도구도 망가뜨리고… 😰
💡 그래, WSL이다!#
Claude Code 재설치하고 잠시 멍때리다가 문득 생각이 들었어요.
“그냥 Linux 환경에서 하면 되잖아?”
이 생각이 든 순간, 왜 진작에 이 생각을 안 했나 싶더라고요. 어차피 제 서버는 Ubuntu인데, Windows에서 억지로 할 이유가 없었죠.
Linux에서는 명령어 파싱도 정확하고, 공식 문서의 예제도 다 Linux 기준이고. Windows에서만 이상하게 안 되는 거였어요.
WSL 설치#
관리자 권한으로 PowerShell을 열고 한 줄이면 끝이에요.
| |
설치가 진행되고, 재부팅하라고 나옵니다. 재부팅하면 Ubuntu가 자동으로 설치되고, 초기 사용자 계정 설정하라고 나와요.
사용자명이랑 비밀번호만 입력하면 설치 완료! 정말 간단하죠?
IntelliJ 터미널 설정 변경#
저는 IntelliJ IDEA를 쓰니까 터미널 설정을 바꿔줬어요.
Settings > Tools > Terminal > Shell path를 wsl.exe -d Ubuntu로 변경.
이제 IntelliJ 터미널을 열면 바로 Ubuntu 환경이 나와요. Windows 터미널 따로 열 필요도 없고 편하더라고요 😊
🛠️ Ubuntu 환경 세팅#
WSL Ubuntu가 설치됐으니 이제 필요한 도구들을 설치해야죠.
Python 설치#
| |
Ubuntu 24는 기본적으로 Python 3.12가 깔려 있지만, python 명령어를 쓰려면 python-is-python3 패키지가 필요해요. 이거 안 깔면 python3로만 실행해야 하거든요.
uv 설치#
| |
설치 스크립트가 자동으로 경로를 설정해주는데, source ~/.bashrc로 환경변수를 리로드해줘야 바로 사용 가능해요.
Node.js 설치 (nvm 사용)#
Claude Code는 Node.js가 필요하니까 nvm으로 설치했어요.
| |
LTS 버전이 자동으로 설치되고 활성화돼요. nvm을 쓰면 나중에 Node 버전 관리도 편하고요.
Claude Code 설치#
| |
이제 준비 끝! 드디어 Serena를 설치할 차례입니다.
🎉 드디어 Serena MCP 설치 성공!#
프로젝트 디렉토리로 이동해서 공식 문서 그대로 입력했어요.
| |
결과: 한 방에 성공! 🎉
4시간 동안 Windows에서 안 되던 게 Ubuntu에서는 그냥 됐어요. 공식 문서 명령어 그대로 복붙만 하면 끝이더라고요.
에러도 없고, 경고도 없고, 그냥 “Installation successful!” 이렇게 뜨는 거예요. 진짜 허무할 정도로 간단했어요 😅
🚀 Serena MCP 사용하기#
설치가 끝났으면 이제 사용할 차례죠.
기본 사용법#
| |
Windows 파일 시스템은 /mnt/c/ 경로로 접근할 수 있어요. C 드라이브가 /mnt/c에 마운트되어 있거든요.
처음 사용 시 - 온보딩#
처음 Serena를 실행하면 온보딩 과정이 필요해요. 프로젝트를 읽고 이해하고 준비하는 과정인데, 채팅으로 “Start Serena onboarding"이라고 하면 됩니다.
이 과정에서 프로젝트 전체를 분석하고, .serena/memories 폴더에 기억을 저장해요. 다음부터는 이 기억을 바탕으로 작업하니까 훨씬 빠르고 정확하죠.
주의할 점은 온보딩에서 많은 파일을 읽기 때문에 토큰을 꽤 소비한다는 거예요. Claude 무료 플랜 쓰시는 분들은 조심하셔야 해요!
실제 사용 예시#
| |
💭 이번에 배운 것들#
Windows에서 uv의 한계#
Windows PowerShell이나 CMD에서는 uv의 명령어 파싱이 제대로 안 되는 것 같아요. 특히 --from 같은 옵션이 포함된 복잡한 명령어는 문제가 생기더라고요.
Linux에서는 같은 명령어가 아무 문제 없이 작동하는 걸 보면, Windows 환경 특유의 이슈인 것 같아요. 셸의 명령어 파싱 방식이 다르거나, 특수문자 처리에 차이가 있는 거겠죠.
Claude Code 먹통 해결법#
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 + 플러그인까지!)