Claude Code에 MCP 서버 연결하기설치부터 연결 확인과 설정 파일 위치까지

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

설정 파일은 어디에 저장되나

등록한 내용이 들어가는 파일은 범위(scope)에 따라 달라집니다. 범위는 이 서버를 어느 프로젝트에서, 누구와 함께 쓸지 정하는 값입니다. 명령에 --scope(줄여서 -s)를 붙여 고릅니다.

어느 프로젝트에서든 쓰고 싶다면 --scope user를 붙여 등록하세요. 팀원과 같은 서버를 쓰려면 --scope project가 맞습니다.

project 범위에는 주의할 점이 있습니다. 대화형으로 쓸 때는 .mcp.json의 서버를 쓰기 전에 승인을 묻습니다. 반면 claude -p 같은 비대화형 실행은 묻지 않고 바로 불러옵니다. 남이 만든 저장소를 받았다면 .mcp.json부터 열어 보세요.

승인 선택을 처음 상태로 되돌리려면 claude mcp reset-project-choices를 입력합니다.

Claude Desktop을 함께 쓴다면 그쪽 설정 파일도 알아 두면 좋습니다. Claude 메뉴의 "Settings..."에서 Developer 탭의 "Edit Config"를 누르면 열립니다. 파일은 아래 위치에 있습니다.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

그곳에 이미 서버를 등록해 두었다면 claude mcp add-from-claude-desktop으로 Claude Code에 가져올 수 있습니다. 가져올 서버를 고르는 창이 뜹니다. 이 기능은 macOS와 WSL(Windows에서 리눅스를 돌리는 환경)에서만 동작합니다.

막히기 쉬운 네 군데

목록에 Failed to connect가 뜹니다

보이는 것: claude mcp list에서 서버 옆에 ✘ Failed to connect가 표시됩니다.

왜 그런지: 설정은 저장됐지만 Claude Code가 서버를 띄우거나 서버와 대화하는 데 실패했습니다. 목록 명령 자체가 고장 난 상황은 아닙니다.

어떻게 하는지: 서버 명령만 떼어 터미널에서 직접 실행해 보세요. 공식 문서도 이 방법으로 오류 메시지를 확인하라고 안내합니다. 경로가 절대 경로인지도 함께 확인합니다.

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

환경 변수를 넣었더니 이름이 거부됩니다

보이는 것: API 키 같은 값을 --env로 넘겼더니 등록이 거부됩니다.

왜 그런지: --env는 KEY=value 쌍을 여러 개 받습니다. 바로 뒤에 서버 이름이 오면 그 이름까지 또 하나의 쌍으로 읽고 거부합니다.

어떻게 하는지: --env와 서버 이름 사이에 다른 옵션을 하나 끼워 넣습니다. 공식 문서의 예처럼 --transport stdio를 사이에 두면 됩니다.

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

서버가 뜨기 전에 연결을 포기합니다

보이는 것: 명령을 직접 치면 잘 도는데, Claude Code에서는 연결되지 않습니다.

왜 그런지: Claude Code는 서버가 뜰 때까지 정해진 시간만 기다립니다. 서버가 왜 늦게 뜨는지, 원인은 문서에 나와 있지 않습니다.

어떻게 하는지: MCP_TIMEOUT 값을 밀리초 단위로 늘려 Claude Code를 켭니다. 아래는 10초로 늘린 예입니다.

MCP_TIMEOUT=10000 claude

Claude Desktop에서 일부 서버만 넘어옵니다

보이는 것: 가져오기를 했는데 몇몇 서버가 빠졌다는 안내가 나옵니다.

왜 그런지: Claude Code의 서버 이름에는 영문자, 숫자, 하이픈, 밑줄만 들어갈 수 있습니다. Claude Desktop은 이 제한이 없어 띄어쓰기가 든 이름도 허용합니다.

어떻게 하는지: 거부된 이름만 바꿔 claude mcp add로 다시 등록하세요. 참고로 v2.1.205 이전에는 이름 하나가 틀리면 가져오기 전체가 멈췄습니다.

여기서 더 나아가려면

공식 MCP 서버 저장소에는 공식 서버와 커뮤니티 서버가 모여 있습니다. 다른 도구에서 데이터를 복사해 대화창에 붙여 넣는 일이 잦다면, 그 도구의 서버부터 찾아보세요. 다만 바깥 내용을 가져오는 서버는 숨은 지시가 섞여 들어올 위험이 있으니, 믿을 수 있는 서버만 연결하세요.

이상으로 글 마치겠습니다.

출처

• Connect to local MCP servers (Model Context Protocol 공식 문서)
• Connect Claude Code to tools via MCP (Claude Code 공식 문서)