MCP 서버 첫 연결, Claude Code에 내 도구 물리는 법

Claude Code 입문

Claude Code에 MCP 서버를 연결하면, 외부 도구와 데이터를 자유롭게 가져다 쓸 수 있어요. 파일시스템 MCP 서버를 직접 연결하면서 전체 과정을 따라해 봐요.

📌 3줄 요약

• MCP 서버는 Claude Code에 외부 도구·데이터 접근 능력을 추가해주는 연결 규격이에요.
• 파일시스템 MCP 서버를 /mcp 명령어 한 줄로 등록하고 바로 사용할 수 있어요.
• MCP 서버 경로는 꼭 필요한 폴더만 좁게 지정해서 보안을 지키는 게 중요해요.

📑 목차

• 1. MCP 서버가 뭔지 30초 만에 이해하기
• 2. MCP 서버 연결을 위한 사전 준비
• 3. 파일시스템 MCP 서버 실전 연결하기
• 4. MCP 서버 연결 후 활용 팁과 주의점

MCP 서버가 뭔지 30초 만에 이해하기

MCP는 Model Context Protocol의 약자예요.

쉽게 말하면, Claude Code가 외부 도구나 데이터를 가져다 쓸 수 있게 해주는 연결 규격이에요.

평소 Claude Code는 터미널 명령어와 파일 읽기·쓰기 정도만 할 수 있어요. 그런데 MCP 서버를 연결하면 데이터베이스 조회, 웹 API 호출, 사내 문서 검색 같은 작업도 가능해져요. 예를 들어 프로젝트 폴더 안의 로그 파일을 자동으로 분석하거나, 노션 문서를 직접 읽어오는 식이에요. 이런 작업을 매번 수동으로 하려면 복사·붙여넣기를 반복해야 하는데, MCP 서버가 그 과정을 없애주는 거예요.

🔍 비유로 이해하기

비유하자면 스마트폰에 앱을 설치하는 것과 비슷해요. 스마트폰 자체로도 쓸 수 있지만, 앱을 깔면 할 수 있는 일이 훨씬 많아지는 것처럼 MCP 서버가 Claude Code의 능력을 확장해 줘요. 카카오톡 앱을 깔아야 메시지를 보낼 수 있는 것처럼, MCP 서버를 연결해야 Claude Code가 외부 도구를 쓸 수 있다고 생각하면 돼요.

MCP 서버는 로컬 컴퓨터에서 실행되는 작은 프로그램이에요. Claude Code가 필요할 때 이 프로그램에 요청을 보내고, 결과를 받아서 활용하는 구조예요. 서버라고 하면 뭔가 거창해 보이지만, 실제로는 터미널에서 돌아가는 가벼운 스크립트에 가까워요. 클라우드 서버를 따로 띄울 필요도 없고, 내 컴퓨터 안에서 Claude Code와 직접 통신하는 방식이에요.

💬 직접 써보니까 MCP의 핵심은 "Claude Code가 몰랐던 정보에 접근할 수 있게 되는 것"이었어요. 설정만 한번 해두면 매번 수동으로 데이터를 복사·붙여넣기 할 필요가 없어져요. 특히 여러 파일을 동시에 다루거나 외부 서비스와 연동해야 할 때 진가가 드러나요.

MCP 서버 연결을 위한 사전 준비

MCP 서버를 연결하려면 먼저 확인할 것이 두 가지 있어요. Claude Code가 최신 버전인지, 그리고 Node.js가 설치되어 있는지 확인해야 해요. 두 가지 모두 터미널에서 명령어 한 줄이면 바로 확인할 수 있어요.

확인 단계 ①

Claude Code 버전은 터미널에서 아래 명령어로 확인할 수 있어요.

claude --version

 

최신 버전이 아니라면 npm update -g @anthropic-ai/claude-code 명령어로 업데이트하면 돼요.

⚠️ 주의: 버전이 너무 오래되면 MCP 관련 기능 자체가 없을 수 있으니 꼭 확인해 주세요.

확인 단계 ②

Node.js는 대부분의 MCP 서버가 실행에 필요로 하는 런타임(runtime, 프로그램 실행 환경)이에요. 터미널에 node --version을 입력해서 v18 이상이 나오면 준비 완료예요.

 

Node.js가 없다면 공식 사이트(nodejs.org)에서 LTS 버전을 내려받아 설치하면 돼요. 설치 후 터미널을 한번 껐다 켜야 명령어가 인식돼요.

💡 팁: Windows 사용자는 설치 마법사에서 기본 옵션 그대로 "Next"만 눌러도 충분해요. Mac 사용자는 Homebrew로 brew install node를 실행해도 돼요.

다음으로 MCP 서버 설정 파일의 위치를 알아야 해요. Claude Code는 ~/.claude/settings.json 파일에서 MCP 서버 목록을 읽어와요. 이 파일 안에 등록된 서버 정보를 보고 Claude Code가 시작할 때 자동으로 연결을 시도하는 거예요.

이 파일이 아직 없다면 Claude Code가 자동으로 만들어 주니 걱정하지 않아도 돼요. 수동으로 만들 필요 없이, 명령어 한 줄이면 등록이 끝나요. 직접 JSON 파일을 편집해서 추가할 수도 있지만, 처음에는 /mcp 명령어를 쓰는 게 훨씬 편해요.

파일시스템 MCP 서버 실전 연결하기

가장 쉽게 시작할 수 있는 MCP 서버는 파일시스템(filesystem) 서버예요. 이 서버를 연결하면 Claude Code가 지정한 폴더의 파일을 읽고, 검색하고, 수정하는 도구를 추가로 갖게 돼요. 기존에도 파일 접근이 가능하지만, MCP 파일시스템 서버는 디렉토리 트리 탐색이나 파일 메타데이터 조회 같은 기능을 더 제공해요.

Claude Code 안에서 /mcp 명령어를 입력하면 MCP 서버 관리 메뉴가 나타나요. 여기서 "Add new MCP server"를 선택하면 돼요. 메뉴가 뜨면 서버 이름, 타입, 실행 명령어를 순서대로 입력하게 돼요.

1

서버 이름 입력
자유롭게 지으면 돼요. 예를 들어 my-files처럼 알아보기 쉬운 이름이 좋아요. 나중에 여러 MCP 서버를 등록하게 되면 이름으로 구분해야 하니까, 용도가 드러나는 이름을 추천해요.

2

서버 타입 선택
stdio를 선택해요.

3

실행 명령어 입력
아래 명령어를 입력해요.

npx -y @modelcontextprotocol/server-filesystem /path/to/your/folder

/path/to/your/folder 부분에는 Claude Code가 접근할 실제 폴더 경로를 넣으면 돼요. Windows 사용자라면 C:/Users/사용자명/Documents 같은 형태로 적어요.

💡 팁: 경로에 한글이나 공백이 있어도 동작하지만, 가능하면 영문 경로가 안정적이에요.

 

등록이 끝나면 Claude Code를 재시작해요. 재시작 후 Claude Code에 "내 문서 폴더에서 최근 수정된 파일을 찾아줘"라고 말하면, MCP 서버가 연결된 것을 확인할 수 있어요.

등록된 MCP 서버 목록은 /mcp 명령어로 언제든 확인 가능해요. 연결 상태가 초록색으로 표시되면 정상 작동 중이라는 뜻이에요. 만약 노란색이나 회색이 보이면 서버가 아직 시작되지 않았거나 경로에 문제가 있는 거예요.

 

MCP 서버 연결 후 활용 팁과 주의점

MCP 서버가 연결되면 Claude Code의 도구 목록에 새로운 항목이 추가돼요. 대화 중에 Claude Code가 알아서 필요한 도구를 골라 사용하기 때문에, 별도 명령어를 외울 필요가 없어요. "이 폴더에서 가장 큰 파일 찾아줘"처럼 자연어로 요청하면, Claude Code가 MCP 도구를 자동으로 선택해서 실행해요. 어떤 도구가 사용됐는지는 응답 중에 도구 호출 알림으로 확인할 수 있어요.

파일시스템 서버 외에도 다양한 MCP 서버가 공개되어 있어요. GitHub, Slack, 데이터베이스, 웹 검색 등 수십 가지 MCP 서버를 같은 방식으로 추가할 수 있어요. Anthropic 공식 문서나 GitHub에서 "MCP servers"로 검색하면 목록을 확인할 수 있어요. 하나씩 추가해 보면서 자기 워크플로우에 맞는 조합을 찾아가는 게 좋아요.

⚠️ 주의: MCP 서버에 넓은 경로(예: C드라이브 전체)를 지정하면 Claude Code가 민감한 파일에 접근할 위험이 있어요.

비밀번호가 저장된 설정 파일이나 개인 문서가 노출될 수 있으니 범위를 좁게 잡는 게 중요해요.

꼭 필요한 폴더만 지정하고, 중요한 파일이 있는 경로는 피하는 것이 안전해요. Claude Code가 MCP 도구를 처음 사용할 때 권한 확인 팝업이 뜨니, 내용을 읽고 허용 여부를 판단하면 돼요. "이 세션에서 항상 허용"을 누르면 같은 도구를 반복 사용할 때마다 팝업이 뜨지 않아서 편해요.

 

🔍 문제 해결 가이드

MCP 서버가 응답하지 않거나 오류가 발생하면 /mcp 메뉴에서 해당 서버를 삭제하고 다시 등록하면 대부분 해결돼요. 서버가 빨간색으로 표시되면 Node.js 버전이나 경로 오타를 먼저 점검하는 것이 좋아요. npx 명령어가 인식되지 않는다면 Node.js 설치가 제대로 안 된 경우가 많으니 node --version부터 다시 확인해 보세요.

💬 MCP 서버 하나만 연결해 봐도 Claude Code가 훨씬 유용해지는 것을 체감할 수 있어요. 특히 반복적으로 같은 폴더의 파일을 다루는 작업이라면, 수동 복사·붙여넣기 대비 작업 시간이 크게 줄어들 거예요. 오늘 파일시스템 서버를 연결해 봤으니, 다음에는 GitHub이나 데이터베이스 MCP 서버에도 도전해 보세요. 한번 감을 잡으면 새 서버 추가는 5분이면 끝나요.

✍️ 마치며

MCP 서버는 Claude Code의 능력을 확장해주는 가장 강력한 방법이에요. 스마트폰에 앱을 설치하듯, MCP 서버를 하나씩 연결하면 Claude Code로 할 수 있는 일이 점점 늘어나요. 오늘 파일시스템 서버 하나를 직접 연결해 봤으니, 이제 다른 MCP 서버도 같은 방법으로 추가해 보세요. 설정은 한번이면 끝나고, 그 뒤로는 자연어로 요청만 하면 돼요.

#ClaudeCode #MCP서버 #파일시스템MCP #AI코딩도구 #ModelContextProtocol