이 포스팅에서는 MCP(Model Context Protocol)가 무엇인지 개념부터 설명하고, Python으로 나만의 MCP 서버를 직접 만들어 Claude Desktop과 연결하는 방법을 단계별로 다룹니다.
MCP 서버를 만들면 Claude가 내 PC의 파일, 데이터베이스, 외부 API 등 다양한 시스템에 직접 접근할 수 있게 됩니다.
1. MCP란 무엇인가?
MCP(Model Context Protocol)는 Anthropic이 만든 오픈 표준 프로토콜입니다.
LLM(대형 언어 모델)이 외부 도구나 데이터에 접근하는 방식을 통일한 규격으로 이해하시면 됩니다.
쉽게 말하면 Claude에게 손발을 달아주는 표준 규격인데요 USB-C 포트처럼, 한 번 규격을 맞춰두면 어떤 도구든 Claude에 꽂아서 쓸 수 있습니다.
| 구분 | 설명 |
| MCP 없이 | Claude는 텍스트만 생성. 외부 시스템 접근 불가 |
| MCP 있으면 | 파일 읽기/쓰기, DB 조회, API 호출 등 실제 행동 가능 |
MCP 서버는 크게 세 가지 기능을 제공합니다.
- Tool : Claude가 호출할 수 있는 함수 (예: 파일 읽기, 계산, API 요청)
- Resource : Claude가 참조할 수 있는 데이터 (예: 문서, DB 내용)
- Prompt : 재사용 가능한 프롬프트 템플릿
이 글에서는 가장 많이 사용하는 Tool 기능을 중심으로 설명하겠습니다.
2. 사전 준비
시작 전에 아래 두 가지가 준비되어 있어야 합니다.
- Python 3.10 이상 설치 (공식 SDK 최소 요구사항)
- Claude Desktop 설치 (claude.ai/download에서 다운로드)
Python 버전 확인 방법은 아래와 같습니다.
python --version
3. fastmcp 설치
MCP 서버를 만드는 가장 간단한 방법은 fastmcp 라이브러리를 사용하는 것입니다. fastmcp는 복잡한 MCP 프로토콜을 감싸서 Python 함수 하나로 도구를 등록할 수 있게 해줍니다.
pip install fastmcp
설치가 완료되면 바로 서버 코드를 작성할 수 있습니다.
4. 첫 번째 MCP 서버 만들기
두 숫자를 더하는 간단한 계산기 MCP 서버를 만들어 보겠습니다.
server.py 파일을 생성하고 아래 코드를 작성하세요.
from fastmcp import FastMCP
# MCP 서버 생성
mcp = FastMCP("나의 첫 번째 MCP 서버")
@mcp.tool
def add(a: int, b: int) -> int:
"""두 숫자를 더합니다."""
return a + b
@mcp.tool
def greet(name: str) -> str:
"""이름을 입력받아 인사말을 반환합니다."""
return f"안녕하세요, {name}님! Claude MCP 서버에 오신 걸 환영합니다."
if __name__ == "__main__":
mcp.run()
코드가 맞게 입력 되었는지 확인을 위해 실행했을때 아래와 같은 화면이 보입니다.
server.py는 Claude Desktop에서 실행되기 때문에 아래 화면과 같이 직접 실행할 필요는 없습니다.
코드 핵심 포인트
| 코드 | 설명 |
FastMCP("서버이름") |
MCP 서버 인스턴스 생성 |
@mcp.tool |
Claude가 호출할 수 있는 도구로 등록 |
| 함수 독스트링 | Claude가 이 도구의 용도를 이해하는 설명. 중요! |
타입 힌트 (int, str) |
fastmcp가 자동으로 파라미터 스키마를 생성할 때 사용 |
mcp.run() |
서버 실행 (STDIO 방식으로 Claude Desktop과 통신) |
5. Claude Desktop에 MCP 서버 연결하기
MCP 서버를 직접 실행하는 것이 아니라, Claude Desktop이 자동으로 서버를 실행하도록 설정 파일에 등록해야 합니다.
5-1. 설정 파일 위치 확인
Claude Desktop의 MCP 설정 파일 위치는 OS에 따라 다릅니다.
| OS | 설정 파일 경로 |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
💡 더 쉬운 방법: Claude Desktop 실행 → 좌측 하단 설정(Settings) → Developer 탭 → Edit Config 클릭
5-2. 설정 파일 작성
설정 파일을 열고 아래 내용을 입력합니다. /절대경로/server.py 부분을 실제 server.py 파일의 절대 경로로 변경하세요.
macOS 예시
# command 경로는 which python 명령어를 입력하여 나온 경로로 실행.
# args 경로는 server.py 가 위치한 절대 경로 입력.
{
"mcpServers": {
"my-server": {
"command": "/Users/ahnlab/projects/test-project/.venv/bin/python",
"args": ["/Users/ahnlab/projects/test-project/server.py"]
}
}
}
Windows 예시
# command 경로는 which python 명령어를 입력하여 나온 경로로 실행.
# args 경로는 server.py 가 위치한 절대 경로 입력.
{
"mcpServers": {
"my-server": {
"command": "python",
"args": ["C:\\Users\\사용자이름\\프로젝트명\\server.py"]
}
}
}
※ Windows에서는 경로에 역슬래시(\)를 두 번(\\) 써야 합니다.
5-3. Claude Desktop 재시작
설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료 후 재실행해야 적용됩니다.
- macOS:
Cmd + Q로 완전 종료 후 재실행 - Windows: 시스템 트레이 아이콘 우클릭 → Quit 후 재실행
6. 연결 확인하기
Claude Desktop을 재실행한 뒤 좌측 하단 설정(Settings) → Developer 탭에 로컬 MCP서버 가 running 이 표시되면 MCP 서버가 정상적으로 연결된 것입니다.
Claude에게 아래와 같이 질문해서 동작을 확인합니다.
15 + 27을 계산해줘
Claude가 MCP 서버의 add 도구를 호출해서 42를 반환하면 성공입니다.
7. 실용적인 예제 - 현재 날짜/시간 반환 도구
조금 더 실용적인 예제로, 현재 날짜와 시간을 반환하는 도구를 추가해 보겠습니다.
from fastmcp import FastMCP
from datetime import datetime
mcp = FastMCP("나의 MCP 서버")
@mcp.tool
def add(a: int, b: int) -> int:
"""두 숫자를 더합니다."""
return a + b
@mcp.tool
def get_current_time() -> str:
"""현재 날짜와 시간을 반환합니다."""
now = datetime.now()
return now.strftime("%Y년 %m월 %d일 %H시 %M분 %S초")
@mcp.tool
def greet(name: str) -> str:
"""이름을 입력받아 인사말을 반환합니다."""
return f"안녕하세요, {name}님!"
if __name__ == "__main__":
mcp.run()
server.py를 수정한 뒤 Claude Desktop을 재시작하면 새 도구가 추가됩니다. Claude에게 "지금 몇 시야?"라고 물으면 get_current_time 도구를 호출해 현재 시간을 알려줍니다.
8. 자주 발생하는 에러와 해결 방법
| 증상 | 원인 및 해결 방법 |
| 로컬 MCP 서버 설정 화면 running 없음 | 설정 파일 경로 오류 또는 JSON 문법 오류 → 파일 경로와 JSON 구조 재확인 |
| 서버가 연결되지 않음 | server.py의 절대 경로가 잘못됨 → 절대 경로를 정확히 입력했는지 확인 |
| 도구 호출 시 오류 발생 | 함수 타입 힌트 누락 → 모든 파라미터에 타입 힌트 추가 |
| Windows 경로 오류 | 역슬래시(\) 대신 \\ 사용했는지 확인 |
9. 응용 아이디어
기본 구조를 익혔다면 아래처럼 다양하게 확장할 수 있습니다.
- 로컬 파일 읽기/쓰기 도구 → Claude가 내 PC 문서를 직접 열람
- 사내 REST API 호출 도구 → Claude가 사내 시스템 데이터를 조회
- SQLite DB 조회 도구 → Claude가 로컬 데이터베이스에 질문
- Python 스크립트 실행 도구 → Claude가 자동화 스크립트를 실행
내용이 유용하셨다면 좋아요&댓글 부탁드립니다.
이 블로그를 이끌어갈 수 있는 강력한 힘입니다!
'IT > AI Tools' 카테고리의 다른 글
| Python으로 ollama API 연동하는 방법 - 로컬 LLM 코드 제어 완전 가이드 (0) | 2026.04.23 |
|---|---|
| ollama로 로컬 LLM 실행하기 — llama3.2, qwen3, mistral 완전 비교 가이드 (0) | 2026.04.22 |
| ollama, git, cursor, uv 설치 방법 - Windows & MacOS AI 실습환경 구성 가이드 (0) | 2026.04.17 |
| GitHub Copilot과 Claude Code를 함께 쓰는 실전 워크플로우 — 두 AI 도구의 최강 조합법 (0) | 2026.04.14 |
| GitHub Copilot 완전 가이드 — VS Code 설치부터 실전 단축키·활용 패턴까지 (0) | 2026.04.13 |
