M MCP모아
튜토리얼

Claude Code MCP 프로젝트 설정 — 팀 공유 .claude/settings.json 작성법

Claude Code MCP 프로젝트 설정을 .claude/settings.json으로 관리하면 팀원 전체가 동일한 MCP 서버를 공유할 수 있습니다. claude mcp add -s project 명령어부터 JSON 형식까지 단계별로 설명합니다.

Claude Code 프로젝트 폴더에 .claude/settings.json 파일이 열려 있고 MCP 서버 설정이 표시된 화면

Claude Code에서 MCP 서버를 프로젝트 범위로 설정하면, .claude/settings.json 파일 하나를 git에 커밋하는 것만으로 팀 전체가 동일한 MCP 환경을 공유할 수 있습니다. 글로벌 설정을 직접 건드리지 않아도 되고, 새로운 팀원이 저장소를 clone하는 순간 바로 동작합니다. 이 가이드에서는 claude mcp add -s project 명령어부터 JSON 수동 편집, 팀 공유 전략까지 실제로 동작하는 예시와 함께 설명합니다.

Claude Code MCP 범위(Scope)란 무엇인가

Claude Code의 MCP 설정에는 세 가지 범위가 있습니다.

범위설정 파일 위치적용 대상git 공유
로컬(Local).claude/settings.local.json본인의 현재 프로젝트비권장 (.gitignore)
프로젝트(Project).claude/settings.json저장소 전체 팀원권장 (git 커밋)
글로벌(User)~/.claude/settings.json모든 프로젝트해당 없음

팀원과 동일한 MCP 서버를 쓰려면 프로젝트 범위를 사용해야 합니다. 글로벌 설정은 개인 편의용이고, 로컬 설정은 API 키처럼 민감 정보를 담을 때만 씁니다.

준비물

  • Claude Code 최신 버전 (npm update -g @anthropic-ai/claude-code)
  • git 저장소(로컬 폴더도 가능)
  • 등록할 MCP 서버의 실행 명령어 (스펙에 주어진 값 사용)

단계별 설정 방법

1단계 — 프로젝트 루트 확인

터미널을 열고 git 저장소 루트(또는 작업 폴더)로 이동합니다. .claude 디렉터리가 없어도 괜찮습니다. 다음 단계에서 자동으로 생성됩니다.

cd /path/to/your-project
ls -a | grep .claude   # 없어도 정상

2단계 — claude mcp add -s project 명령어로 등록

claude mcp add 명령어에 -s project 플래그를 붙이면 프로젝트 범위로 등록됩니다.

# 기본 형식
claude mcp add -s project <서버명> <실행명령> [인자...]

# 예: KorDoc MCP 서버 등록
claude mcp add -s project kordoc npx -- -y kordoc setup

# 예: HWP-MCP 서버 등록
claude mcp add -s project hwp-mcp npx -- -y hwp-mcp

명령 실행 후 .claude/settings.json 파일이 생성(또는 갱신)됩니다.

3단계 — settings.json 내용 확인 및 수동 편집

생성된 파일을 열어 내용을 검토합니다. 아래는 npx 기반 서버 두 개를 등록했을 때의 예시입니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"],
      "env": {}
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"],
      "env": {}
    },
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"],
      "env": {}
    }
  }
}

API 키가 필요한 서버라면 env 객체에 키 이름을 넣되, 실제 값은 절대 settings.json에 넣지 마세요. 대신 OS 환경 변수나 .env 파일을 사용하고, settings.json에는 변수 이름만 남깁니다.

{
  "mcpServers": {
    "some-api-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "API_KEY": ""
      }
    }
  }
}

4단계 — git 커밋으로 팀 공유

git add .claude/settings.json
git commit -m "chore: add project-scope MCP servers (kordoc, hwp-mcp, hwpforge)"
git push

민감 정보가 담길 수 있는 .claude/settings.local.json은 .gitignore에 추가해 두는 것이 좋습니다.

echo ".claude/settings.local.json" >> .gitignore

5단계 — Claude Code 재시작 후 동작 확인

VS Code의 Claude Code 확장이나 터미널 claude 명령을 재시작한 후, 다음 명령으로 등록된 서버 목록을 확인합니다.

claude mcp list

또는 Claude Code 채팅 창에서 /mcp 를 입력하면 현재 활성화된 서버 목록이 표시됩니다. kordoc, hwp-mcp, hwpforge 등이 보이면 성공입니다.

데이터 흐름 한눈에 보기

팀원 A (로컬)              팀원 B (로컬)
.claude/settings.json  →  git clone  →  .claude/settings.json
        ↓                                        ↓
  Claude Code 읽기                         Claude Code 읽기
        ↓                                        ↓
   npx 자동 실행                            npx 자동 실행
        ↓                                        ↓
   MCP 서버 기동           ←동일 서버→        MCP 서버 기동
        ↓                                        ↓
   Claude 에이전트                          Claude 에이전트

팀 A와 B 모두 동일한 settings.json을 바라보기 때문에 서버 버전 불일치 문제가 줄어들고, 신규 팀원 온보딩 시간도 크게 단축됩니다.

흔한 오류와 해결법

”command not found: claude”

Claude Code가 전역 설치되지 않은 경우입니다.

npm install -g @anthropic-ai/claude-code

”Unknown option: -s”

-s project 플래그는 비교적 최근에 추가된 기능입니다. 버전을 확인하고 업데이트하세요.

claude --version
npm update -g @anthropic-ai/claude-code

MCP 서버가 목록에 보이지 않음

  • .claude/settings.json 파일이 저장소 루트가 아닌 하위 폴더에 있는지 확인합니다.
  • JSON 문법 오류가 있으면 서버가 무시됩니다. 터미널에서 cat .claude/settings.json | python3 -m json.tool 로 유효성을 검사하세요.
  • Claude Code를 완전히 종료 후 다시 시작해 보세요.

npx 실행 시 권한 오류 (macOS)

# npm 캐시 폴더 권한 수정
sudo chown -R $(whoami) ~/.npm

프로젝트 범위 MCP 활용 예시: 한국 공문서 처리 팀

한국 행정 서류(HWP, PDF, DOCX)를 다루는 팀이라면 다음 세 서버를 프로젝트 범위로 등록해 두면 유용합니다.

서버주요 기능설치 명령
코르독 (KorDoc)HWP·HWPX·PDF·XLSX·DOCX → Markdown 변환npx -y kordoc setup
HWP-MCP한글(.hwp/.hwpx) 문서 읽기·편집·생성npx -y hwp-mcp
한포지 (HwpForge)HWPX 문서 AI 읽기·쓰기·변환npx -y @hwpforge/mcp

세 서버 모두 API 키가 필요 없어 settings.json에 민감 정보 없이 바로 git 커밋할 수 있습니다. 개발 도구 카테고리에서 더 많은 개발용 MCP 서버를 찾아볼 수 있습니다.

자주 묻는 질문

.claude/settings.json과 ~/.claude/settings.json의 차이는 무엇인가요?

.claude/settings.json은 프로젝트(저장소) 범위로, 해당 폴더 안에서만 적용됩니다. ~/.claude/settings.json은 사용자(글로벌) 범위로 모든 프로젝트에 적용됩니다. 팀 공유가 목적이라면 프로젝트 범위 파일을 git에 커밋하세요.

claude mcp add -s project 명령어가 없다고 나옵니다.

Claude Code 버전이 낮을 수 있습니다. npm update -g @anthropic-ai/claude-code 로 최신 버전으로 업데이트한 뒤 다시 시도하세요.

npx로 실행하는 MCP 서버는 args를 어떻게 지정하나요?

command를 npx로, args 배열에 ["-y", "패키지명"] 형태로 입력합니다. kordoc은 command: npx, args: ["-y", "kordoc", "setup"]으로 설정합니다.

API 키가 필요한 서버의 환경 변수는 어디에 넣나요?

settings.json의 env 객체에 넣을 수 있지만, 비밀 값은 git에 올라가지 않도록 .env 파일이나 OS 환경 변수로 분리하는 것을 권장합니다. settings.json에는 env 키 이름만 빈 문자열로 남기고 실제 값은 별도 관리하세요.

팀원이 clone 후 MCP 서버를 바로 쓸 수 있나요?

settings.json이 git에 포함된 경우, 팀원이 저장소를 clone하면 Claude Code가 자동으로 해당 설정을 읽습니다. npx 기반 서버라면 별도 글로벌 설치 없이 npx가 자동으로 패키지를 내려받아 실행합니다.

프로젝트 범위 설정이 글로벌 설정보다 우선하나요?

네, Claude Code는 프로젝트 범위(.claude/settings.json)를 글로벌(~/.claude/settings.json)보다 우선 적용합니다. 같은 이름의 서버가 양쪽에 모두 있으면 프로젝트 쪽이 사용됩니다.

다음 단계

settings.json 하나로 팀 MCP 환경을 통일했다면, 이제 각 서버를 실제 업무에 연결해 보세요.

이 글과 관련된 MCP 서버