MCP 서버 설치가이드

작성일: 2026-08-20
선행 조건: 공통 준비 완료 (실습 저장소를 이미 받아 둔 상태)
대상 실습: 저장소의 tool/ 모듈 — 생산지표(OEE) 계산 도구
끝나면: Claude Code가 "B라인 어제 OEE 알려줘" 를 암산하지 않고 도구를 호출해 답하는 상태

빠른 설치 (아는 사람용 · 5분)

전제: 공통 준비 완료 + python --version(Mac은 python3)이 3.10 이상.

① Windows · PowerShell 에만

cd C:\harness-edu\tool\mcp-server
python -m pip install --user -r requirements.txt
claude mcp add production-metrics --scope user -- python C:\harness-edu\tool\mcp-server\server.py

① macOS · 터미널 에만

cd ~/harness-edu/tool/mcp-server
python3 -m pip install --user -r requirements.txt
claude mcp add production-metrics --scope user -- python3 ~/harness-edu/tool/mcp-server/server.py

② 확인 → Claude Code 실행 → 입력창에서 도구 호출

터미널에 붙여넣기

claude mcp list

Claude Code 입력창에 붙여넣기

production-metrics 도구로 07-14 B라인 OEE를 구해줘.

1. 이 도구는 무엇인가

MCP 서버 는 AI에게 붙이는 계산기입니다. 이 과정에서 배우는 세 축 중 마지막인 Tool 에 해당합니다.

축	무엇인가	형태	같은 질문에 같은 답?
Agent	역할·경계 (누가)	지시문 파일	—
Skill	지식·절차 (무엇을·어떻게)	AI가 읽는 문서	✗ 모델이 해석
Tool	실행 수단 (무엇으로)	실제 코드	✓ 항상 같음

왜 필요한지는 한 번 보면 바로 이해됩니다. "B라인 어제 OEE(설비종합효율) 알려줘" 를 물었을 때—

도구 없이 — AI가 암산

가동률 0.75쯤, 성능 0.94쯤... OEE 대략 70% 안팎으로 보입니다

도구 있이 — 코드가 계산

{ "availability": 0.75, "performance": 0.9444, "quality": 0.9853,
  "oee": 0.6979, "oee_pct": "69.8%", "bottleneck": "가동률" }

앞은 그럴듯하지만 검증할 수 없고 매번 값이 다릅니다. 뒤는 몇 번을 돌려도 69.8% 이고, 병목이 가동률이라는 진단까지 코드가 계산합니다.

왜 MCP인가: MCP(Model Context Protocol)는 Anthropic이 공개한 오픈 표준입니다. 서버 하나를 만들어 두면 Claude Code도, Codex도, 앞으로 나올 다른 AI도 그대로 씁니다. 사내 계산 도구를 "도구별로 다시 만들지 않는" 방법이고, 이것이 이 실습의 핵심 메시지입니다.

이 실습에서 붙이는 서버(production-metrics)에는 도구가 3개 있습니다.

도구	하는 일
`list_records`	조회 가능한 라인·날짜 목록
`compute_oee`	지정한 라인·날짜의 OEE 계산 + 병목 진단
`defect_ppm`	불량률(ppm) 계산

2. 설치 전 확인

항목	필요한 것	확인·대처
선행 설치	공통 준비 전체 완료 (Python 포함) + 실습 저장소	Windows / macOS
Python	3.10 이상	공통 준비에서 이미 설치 — Win 3-9 / Mac 3-9. 3-1절에서 확인만
Codex (선택)	같은 도구를 Codex에도 붙일 때만	Codex CLI 설치가이드
관리자 권한	필요 없음	패키지를 `--user` 로 내 계정에만 설치합니다

이 문서는 6차시 필수이고, Python이 이미 깔려 있다는 전제로 시작합니다.

Python 설치는 공통 준비의 일입니다 — Windows 3-9절 / macOS 3-9절. 거기서 끝내고 오면 이 문서는 5분이면 됩니다. 여기서 다루는 것은 패키지 하나 설치 + Claude Code에 연결, 두 가지뿐입니다.

Python을 쓰는 것은 6차시뿐입니다. 다른 차시(엑셀·문서·하네스 실습)에는 필요하지 않습니다.

내 PC에 무엇이 남나: 이 실습이 설치하는 것은 파이썬 패키지 하나(mcp)뿐이고, --user 옵션으로 내 계정에만 들어갑니다. 관리자 권한이 필요 없고, 정리는 python -m pip uninstall mcp 한 줄입니다.

3. 설치 절차

3-1. Python이 준비됐는지 확인

Python 설치는 이 문서가 아니라 공통 준비에서 합니다. 여기서는 준비가 됐는지만 확인합니다.

Windows

PowerShell에 붙여넣기

python --version

macOS

터미널에 붙여넣기

python3 --version

예상 결과: Python 3.13.1 처럼 3.10 이상이면 다음 절로 넘어갑니다.

버전이 안 나오거나 3.10 미만이면 공통 준비의 Python 절을 먼저 하세요 — Windows 3-9절 / macOS 3-9절. 여기서 되돌아가는 것이 정상입니다. 이 문서는 Python이 있다는 전제로 시작합니다.

파이썬을 부르는 이름이 OS마다 다릅니다. 이 문서에서 계속 나오니 여기서 한 번에 정리합니다.

내 PC	쓰는 명령	다른 쪽 명령을 쓰면
Windows	`python`	`python3` → "앱 실행 별칭" 오류 또는 Microsoft Store 창이 열립니다
macOS	`python3`	`python` → `command not found`

아래 모든 명령 블록에는 Windows · macOS 라벨이 붙어 있습니다. 본인 OS 라벨이 붙은 것만 복사하세요.

3-2. 도구 폴더로 이동

Windows

PowerShell에 붙여넣기

cd C:\harness-edu\tool\mcp-server

macOS

터미널에 붙여넣기

cd ~/harness-edu/tool/mcp-server

파일이 맞게 있는지 확인합니다.

터미널에 붙여넣기

ls

예상 결과: 세 항목이 보입니다.

예상 화면

data    requirements.txt    server.py

경로를 찾을 수 없다고 나오면: 공통 준비의 git clone 단계가 빠졌습니다. 실습 저장소 받기를 먼저 하세요.

3-3. 패키지 설치 (한 줄)

이 도구가 쓰는 패키지 하나만 설치합니다. 본인 OS 것만 쓰세요.

Windows · PowerShell

python -m pip install --user -r requirements.txt

macOS · 터미널

python3 -m pip install --user -r requirements.txt

예상 결과: 설치 로그가 흐르고 마지막에 Successfully installed mcp-1.x.x ... 가 나옵니다. 1~3분.

예상 화면 (마지막 줄)

Successfully installed mcp-1.19.0 ...   ← 1 로 시작하면 정상

이렇게 나오면 오류

ERROR: Could not find a version... / 시간 초과 → 사내 프록시가 파이썬 저장소를 막고 있습니다. 휴대폰 테더링으로 재시도하고, 계속 막히면 IT 담당자에게 pypi.org 접근을 요청하세요.
python 을 찾을 수 없다 → 3-1절로. Windows는 python, macOS는 python3 입니다.
externally-managed-environment (주로 Homebrew 파이썬) → 문제 해결 ②의 가상환경 방식을 쓰세요.
requirements.txt 가 없다 → tool/mcp-server 폴더가 아닌 곳입니다. 3-2절로.

--user 는 무슨 뜻인가 — 내 계정에만 설치한다는 뜻입니다. 관리자 권한이 필요 없고, 다른 사용자 환경을 건드리지 않습니다. 나중에 지울 때는 python -m pip uninstall mcp 한 줄입니다.

버전은 requirements.txt 에 <2 로 고정되어 있습니다. MCP 패키지 2.0 에서 FastMCP 위치가 mcp.server.fastmcp → mcp.server.mcpserver 로 바뀌어, 2.x 를 설치하면 이 실습의 server.py 가 동작하지 않습니다.

3-4. 계산이 맞는지 확인

AI에 붙이기 전에 계산 자체를 확인합니다. (AI 없이 코드만 실행)

Windows · PowerShell

python -c "from server import compute_oee; print(compute_oee('B','2026-07-14'))"

macOS · 터미널

python3 -c "from server import compute_oee; print(compute_oee('B','2026-07-14'))"

예상 결과: 계산 결과가 그대로 출력됩니다.

예상 화면

{'availability': 0.75, 'performance': 0.9444, 'quality': 0.9853,
 'oee': 0.6979, 'oee_pct': '69.8%', 'bottleneck': '가동률'}

몇 번을 실행해도 값이 같습니다. 이것이 Skill(암산)과 결정적으로 다른 점입니다.

이렇게 나오면 오류

No module named 'mcp.server.fastmcp' → 2.x 가 깔려 있습니다 → 문제 해결 ①
No module named 'mcp' → 3-3절 설치가 안 됐거나 다른 파이썬에 설치됐습니다 → 문제 해결 ①
No module named 'server' → tool/mcp-server 폴더가 아닌 곳입니다 (ls 에 server.py 가 보여야 합니다)

3-5. Claude Code에 등록 (스코프 주의)

tool/mcp-server 폴더에서 실행합니다.

--scope user 를 꼭 붙이세요. 붙이지 않으면 기본값이 local 이라서 지금 이 폴더에서만 도구가 보입니다.

스코프	어디서 보이나	이 과정에서
user	내 계정의 모든 폴더	✅ 이것을 사용
local (기본값)	등록한 그 폴더에서만, 나만	❌ 7차시에서 `my-harness` 폴더로 옮기면 도구가 사라집니다
project	`.mcp.json` 으로 팀 공유	△ 팀에 배포할 때 (9-A절 참고)

Windows

Windows · PowerShell

claude mcp add production-metrics --scope user -- python C:\harness-edu\tool\mcp-server\server.py

macOS

macOS · 터미널

claude mcp add production-metrics --scope user -- python3 ~/harness-edu/tool/mcp-server/server.py

예상 결과: 서버가 등록됐다는 메시지가 나옵니다. -- 뒤가 "서버를 실행하는 명령"입니다.

server.py 는 전체 경로로 씁니다. user 스코프는 다른 폴더에서도 이 서버를 띄우기 때문에, 상대경로로 등록하면 그 폴더에서 파일을 찾지 못합니다. 저장소를 다른 곳에 받았다면 위 경로만 본인 것으로 바꾸세요.

등록 목록을 확인합니다.

터미널에 붙여넣기

claude mcp list

예상 결과: 목록에 production-metrics 가 보입니다. 스코프까지 확인하려면 claude mcp get production-metrics 를 실행하세요.

다른 폴더에서도 되는지 확인해 보세요. 아무 폴더로 cd 한 뒤 claude mcp list 에 여전히 보이면 user 스코프로 잘 등록된 것입니다. local 이면 목록에서 사라집니다.

잘못 등록했다면 지우고 다시 하면 됩니다 — claude mcp remove production-metrics 후 위 명령을 --scope user 를 붙여 재실행하세요.

4. 설치 확인

Claude Code를 실행하고(같은 폴더에서 claude), 입력창에서 확인합니다.

Claude Code 입력창에 붙여넣기

/mcp

예상 결과: production-metrics 가 connected 상태로 보입니다.

목록에 없거나 failed 라면: Claude Code를 /exit 로 나갔다가 다시 실행하세요(등록 후 재시작 필요). 그래도 안 되면 문제 해결 ②.

최종 체크리스트

python --version (mac: python3) 이 3.10 이상
3-3절 설치 후 Successfully installed mcp-1.x 확인
3-5절 계산 결과가 69.8% 로 출력
claude mcp list 에 production-metrics 표시 — 다른 폴더에서도 보일 것(user 스코프)
Claude Code에서 /mcp 가 connected 표시
아래 6절 첫 동작 테스트 통과

5. 초기 설정·연동

5-1. 도구 승인 화면에서 무엇을 위임하는가

AI가 도구를 처음 호출할 때 승인을 물어봅니다. 이때 위임하는 것은 "이 폴더의 CSV를 읽어 계산하는 코드를 실행할 권한" 입니다. 외부로 데이터를 보내지 않고, 계산은 내 PC에서 일어납니다.

안전 원칙
① 이 서버는 tool/mcp-server/data/production.csv 가상 데이터만 읽습니다.
② 실제 생산·재무 데이터를 이 폴더에 복사해 넣지 않습니다. 실습은 가상 데이터로 충분합니다.
③ 사내 실 데이터에 붙이는 것은 교육 이후 IT·보안 검토를 거친 뒤 진행합니다.

5-2. 같은 도구를 Codex에도 붙이기 (선택)

Codex에는 스코프 개념이 없고 등록하면 전역으로 적용됩니다. MCP가 오픈 표준이라는 것을 여기서 확인합니다. 코드를 한 줄도 바꾸지 않고 다른 AI에 붙입니다. (Codex CLI 를 설치한 경우에만)

Windows · PowerShell

codex mcp add production-metrics -- python "C:\harness-edu\tool\mcp-server\server.py"

macOS · 터미널

codex mcp add production-metrics -- python3 ~/harness-edu/tool/mcp-server/server.py

등록 확인

codex mcp list

관찰 포인트: 스킬(문서)은 도구마다 복사해야 했지만, Tool은 하나의 서버를 양쪽이 각자 등록해 공유합니다. 계산 로직의 원본이 한 곳뿐이라 고칠 때도 한 번만 고치면 됩니다.

6. 첫 동작 테스트 (5분)

Claude Code 입력창에서 순서대로 넣어 보세요.

① 도구가 불리는지 확인

production-metrics 도구로 07-14 B라인 OEE를 구해줘.

예상 결과: AI가 compute_oee 를 호출하고(화면에 도구 호출 표시가 보입니다) 69.8% 를 답합니다. 승인을 물으면 승인하세요.

② 도구 + 해석을 함께

production-metrics 도구로 07-14 A·B·C 세 라인의 OEE를 구하고,
가장 낮은 라인의 병목이 무엇인지, 개선하려면 어디를 봐야 하는지 정리해줘.

예상 결과: 도구를 세 번 호출해 정확한 값을 받아 온 뒤, 거기에 해석만 얹습니다. — "정확한 산수는 도구, 해석은 모델" 이라는 분업이 눈으로 보입니다.

AI가 도구를 안 부르고 직접 암산하려 하면: "compute_oee 도구를 사용해서" 라고 명시하세요. 도구 설명이 구체적일수록 자동 호출이 잘 됩니다 — 이것이 도구 설명문(docstring)도 지시서인 이유입니다.

7. 문제 해결

① `No module named 'mcp'` 또는 `'mcp.server.fastmcp'`

메시지	원인 · 해결
`No module named 'mcp.server.fastmcp'` (`mcp` 는 있음)	2.x 가 깔려 있습니다. 2.0 에서 이 경로가 `mcp.server.mcpserver` 로 바뀌었습니다. 아래 명령으로 1.x 로 맞추세요.
`No module named 'mcp'`	설치가 안 됐거나 다른 파이썬에 설치됐습니다. 아래 명령을 그대로 실행하세요.

Windows · PowerShell

python -m pip install --user "mcp[cli]>=1.2.0,<2"

macOS · 터미널

python3 -m pip install --user "mcp[cli]>=1.2.0,<2"

설치된 버전 확인 — 1 로 시작해야 합니다.

터미널에 붙여넣기 (mac 은 python3)

python -m pip show mcp

AI가 도구를 부를 때만 이 오류가 난다면 등록된 명령이 다른 파이썬을 가리키는 것입니다. claude mcp remove production-metrics 후 3-5절 명령으로 다시 등록하세요.

② `externally-managed-environment` 로 설치가 막힙니다

원인: Homebrew 파이썬 등 일부 환경은 시스템 파이썬에 직접 설치하는 것을 막습니다(--user 포함).
해결: 이 폴더 안에만 쓰는 격리된 파이썬 환경을 만들어 씁니다. 아래 두 줄을 실행하고, 이후 python 대신 표시된 경로를 쓰세요.

macOS · 터미널

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt

검증과 등록은 이렇게 바뀝니다.

macOS · 터미널

./.venv/bin/python -c "from server import compute_oee; print(compute_oee('B','2026-07-14'))"
claude mcp add production-metrics --scope user -- ~/harness-edu/tool/mcp-server/.venv/bin/python ~/harness-edu/tool/mcp-server/server.py

Windows에서는 이 오류가 거의 나지 않습니다. 혹시 난다면 위 명령의 python3 → python, ./.venv/bin/python → .\.venv\Scripts\python.exe 로 바꿔 쓰면 됩니다.

③ 등록을 지우고 다시 하고 싶습니다

터미널에 붙여넣기

claude mcp remove production-metrics

이후 3-6절을 다시 실행합니다. claude mcp get production-metrics 로 현재 등록 내용을 볼 수 있습니다.

④ Windows: `Activate.ps1` 을 로드할 수 없습니다

이 문서는 가상환경을 켜지 않고 파이썬을 직접 지정하므로 이 오류를 만나지 않습니다. 다른 자료를 보고 activate 를 시도했다면, 켜지 말고 3-3절 방식(.\.venv\Scripts\python.exe -m pip ...)을 쓰면 됩니다.

그래도 켜고 싶다면 아래로 본인 계정 범위만 완화합니다(Y 승인). 회사 정책으로 실패하면 우회하지 말고 IT 담당자에게 요청하세요.

Windows · PowerShell

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

⑤ 한글 데이터가 깨져 보입니다

Windows 11의 터미널(Windows Terminal) 로 실행하세요. 데이터 파일 자체는 UTF-8로 정상입니다.

8. 제거·연동 해제

1) 등록 해제

터미널에 붙여넣기

claude mcp remove production-metrics

Codex에도 붙였다면: codex mcp remove production-metrics

2) 패키지 제거

터미널에 붙여넣기 (mac 은 python3)

python -m pip uninstall mcp

y 를 입력해 확인합니다. 문제 해결 ②의 가상환경 방식을 썼다면 tool/mcp-server/.venv 폴더만 지우면 됩니다.

3) Python 제거 (원한다면) — Windows: 설정 → 앱 → 설치된 앱 → Python → 제거. macOS: 시스템 파이썬은 지우지 마세요.

9. 다른 연결 방법 (필요할 때만)

A. `.mcp.json` 파일로 등록 (팀 공유용 · project 스코프)

프로젝트 루트에 아래 파일을 두면, 저장소를 받은 팀원 모두가 같은 도구를 씁니다. 경로는 각자 환경에 맞게(절대경로 권장) 조정합니다.

.mcp.json

{
  "mcpServers": {
    "production-metrics": {
      "command": "python",
      "args": ["tool/mcp-server/server.py"]
    }
  }
}

Claude Code를 다시 시작하면 인식하며, 처음 로드 시 신뢰 여부를 물어볼 수 있습니다.

B. 원격(HTTP) 서버 — 심화

지금은 내 PC에서 python server.py 를 띄우는 방식입니다. 팀 전체가 공유하려면 서버를 HTTP로 올리고 아래처럼 등록합니다. 로컬 계산기가 사내 API로 승격되는 단계입니다.

터미널에 붙여넣기

claude mcp add my-remote --transport http https://mcp.example.com/mcp

C. 이미 공개된 MCP 서버 쓰기

세상에는 이미 공개된 MCP 서버가 많습니다. "만들기 전에 이미 누가 만든 도구가 없는지 찾는다" 도 중요한 감각입니다. 실습 심화 과제는 저장소 tool/README.md 7절을 보세요.

10. 다음 단계

교육커리큘럼으로설치가 모두 끝났습니다. Tool 모듈 실습으로 이동하세요. 설치설치가이드 홈전체 설치 현황을 다시 확인합니다. 교안tool/ 모듈 교안도구를 직접 만들고 확장하는 심화 과제.

확인한 출처

이 저장소의 tool/README.md, tool/register-claude-code.md, tool/register-codex.md
MCP 공식 소개 — modelcontextprotocol.io
Claude Code MCP 등록 — code.claude.com/docs/en/mcp
Codex MCP 등록 — developers.openai.com/codex

빠른 설치 (아는 사람용 · 5분)

1. 이 도구는 무엇인가

2. 설치 전 확인

3. 설치 절차

3-1. Python이 준비됐는지 확인

3-2. 도구 폴더로 이동

3-3. 패키지 설치 (한 줄)

3-4. 계산이 맞는지 확인

3-5. Claude Code에 등록 (스코프 주의)

4. 설치 확인

5. 초기 설정·연동

5-1. 도구 승인 화면에서 무엇을 위임하는가

5-2. 같은 도구를 Codex에도 붙이기 (선택)

6. 첫 동작 테스트 (5분)

7. 문제 해결

① No module named 'mcp' 또는 'mcp.server.fastmcp'

② externally-managed-environment 로 설치가 막힙니다

③ 등록을 지우고 다시 하고 싶습니다

④ Windows: Activate.ps1 을 로드할 수 없습니다

⑤ 한글 데이터가 깨져 보입니다

8. 제거·연동 해제

9. 다른 연결 방법 (필요할 때만)

A. .mcp.json 파일로 등록 (팀 공유용 · project 스코프)

B. 원격(HTTP) 서버 — 심화

C. 이미 공개된 MCP 서버 쓰기

10. 다음 단계

확인한 출처

① `No module named 'mcp'` 또는 `'mcp.server.fastmcp'`

② `externally-managed-environment` 로 설치가 막힙니다

④ Windows: `Activate.ps1` 을 로드할 수 없습니다

A. `.mcp.json` 파일로 등록 (팀 공유용 · project 스코프)