[ 트렌드] MCP 서버 구축 가이드: Python FastMCP 활용

# MCP 서버 구축 가이드: Python FastMCP 활용

AI 에이전트가 외부 도구와 데이터에 접근할 수 있게 해주는 MCP 서버를, Python으로 처음부터 만들어봅니다. 이 가이드를 따라하면 30분 안에 동작하는 MCP 서버를 완성할 수 있습니다.

## MCP란 무엇인가

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 프로토콜로, LLM 애플리케이션과 외부 데이터 소스·도구를 표준화된 방식으로 연결합니다. 웹 API가 브라우저와 서버를 연결하듯, MCP는 AI 모델과 외부 세계를 연결하는 규격입니다.

현재 최신 사양은 **2025-11-25 버전**이며, 비동기 작업(Tasks), OAuth 2.1 기반 인증, 확장(Extensions) 시스템 등이 추가되었습니다. Claude Desktop, VS Code, Cursor, ChatGPT 등 주요 AI 클라이언트들이 MCP를 지원합니다.

MCP 서버가 제공할 수 있는 세 가지 핵심 기능은 다음과 같습니다.

- **Tools**: LLM이 호출할 수 있는 함수 (API 호출, 계산, 파일 처리 등)
- **Resources**: 읽기 전용 데이터 소스 (설정, 파일 내용, DB 레코드 등)
- **Prompts**: 재사용 가능한 대화 템플릿

이 튜토리얼에서는 **Tools**를 중심으로 실용적인 MCP 서버를 구축합니다.

## 사전 준비

시작하기 전에 다음 환경이 필요합니다.

| 항목 | 요구사항 |
|------|---------|
| Python | 3.10 이상 |
| pip 또는 uv | 패키지 설치용 |
| 코드 편집기 | VS Code 권장 |
| MCP 클라이언트 | Claude Desktop, VS Code, 또는 Cursor |

Python 버전을 확인합니다:

```bash
python3 --version
# Python 3.10 이상이어야 합니다
```

## Step 1: 프로젝트 설정

프로젝트 디렉토리를 만들고 가상환경을 설정합니다.

```bash
# 프로젝트 디렉토리 생성
mkdir my-mcp-server
cd my-mcp-server

# 가상환경 생성 및 활성화
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate

# FastMCP 설치
pip install fastmcp
```

`uv`를 사용하는 경우(더 빠름):

```bash
pip install uv
uv venv
source .venv/bin/activate
uv pip install fastmcp
```

## Step 2: 기본 MCP 서버 만들기

`server.py` 파일을 생성하고 가장 간단한 형태의 MCP 서버를 작성합니다.

```python
from fastmcp import FastMCP

# 서버 인스턴스 생성
mcp = FastMCP("My First MCP Server")

@mcp.tool
def add(a: int, b: int) -> int:
"""두 숫자를 더합니다."""
return a + b

@mcp.tool
def greet(name: str) -> str:
"""이름을 받아 인사말을 반환합니다."""
return f"안녕하세요, {name}님! 반갑습니다."

if __name__ == "__main__":
mcp.run()
```

이것만으로 MCP 서버가 완성됩니다. FastMCP는 함수의 타입 힌트와 독스트링을 자동으로 분석하여 도구 스키마를 생성합니다. 함수 이름이 도구 이름이 되고, 독스트링이 도구 설명이 되며, 타입 힌트가 입력 스키마로 변환됩니다.

서버를 실행합니다:

```bash
python server.py
```

## Step 3: 실용적인 도구 추가하기

이번에는 실제로 쓸 수 있는 도구를 만들어봅니다. 웹에서 환율 정보를 가져오는 도구를 추가합니다.

```python
from fastmcp import FastMCP
import httpx
from datetime import datetime

mcp = FastMCP("Finance Tools")

@mcp.tool
def get_exchange_rate(base: str = "USD", target: str = "KRW") -> dict:
"""실시간 환율 정보를 조회합니다.

Args:
base: 기준 통화 코드 (예: USD, EUR, JPY)
target: 대상 통화 코드 (예: KRW, USD, EUR)
"""
url = f"https://api.exchangerate-api.com/v4/latest/{base}"
response = httpx.get(url, timeout=10)
data = response.json()

rate = data["rates"].get(target)
if rate is None:
return {"error": f"통화 코드 '{target}'을 찾을 수 없습니다."}

return {
"base": base,
"target": target,
"rate": rate,
"updated": data.get("date", str(datetime.now().date()))
}

@mcp.tool
def calculate_exchange(
amount: float,
base: str = "USD",
target: str = "KRW"
) -> dict:
"""금액을 환전 계산합니다.

Args:
amount: 환전할 금액
base: 원래 통화 코드
target: 변환할 통화 코드
"""
rate_info = get_exchange_rate(base, target)
if "error" in rate_info:
return rate_info

converted = round(amount * rate_info["rate"], 2)
return {
"original": f"{amount} {base}",
"converted": f"{converted} {target}",
"rate": rate_info["rate"]
}

if __name__ == "__main__":
mcp.run()
```

## Step 4: Resource 추가하기

Resource는 LLM에 읽기 전용 데이터를 제공합니다. 서버 설정이나 참고 데이터를 노출할 때 유용합니다.

```python
import json

@mcp.resource("config://app/settings")
def app_settings() -> str:
"""애플리케이션 설정 정보를 제공합니다."""
return json.dumps({
"version": "1.0.0",
"supported_currencies": ["USD", "KRW", "EUR", "JPY", "GBP", "CNY"],
"api_source": "exchangerate-api.com"
})

@mcp.resource("guide://{topic}")
def usage_guide(topic: str) -> str:
"""사용 가이드를 제공합니다."""
guides = {
"exchange": "환율 조회: get_exchange_rate(base='USD', target='KRW')로 사용",
"calculate": "환전 계산: calculate_exchange(amount=100, base='USD', target='KRW')로 사용"
}
return guides.get(topic, f"'{topic}' 주제의 가이드를 찾을 수 없습니다.")
```

`guide://{topic}` 형태의 동적 URI를 사용하면, `guide://exchange`와 같이 요청할 때 `topic` 파라미터에 `exchange`가 자동으로 매핑됩니다.

## Step 5: Claude Desktop에 연결하기

완성된 서버를 Claude Desktop에 연결합니다. Claude Desktop 설정 파일을 편집합니다.

**macOS:**
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
code %APPDATA%\Claude\claude_desktop_config.json
```

다음 내용을 추가합니다:

```json
{
"mcpServers": {
"finance-tools": {
"command": "python",
"args": ["/절대/경로/my-mcp-server/server.py"],
"env": {}
}
}
}
```

Claude Desktop을 재시작하면, 대화 입력창 근처에 도구 아이콘이 표시됩니다. 이제 Claude에게 "1000달러를 원화로 환산해줘"라고 말하면 자동으로 MCP 도구를 호출합니다.

## Step 6: VS Code / Cursor에서 사용하기

VS Code에서 MCP 서버를 사용하려면 Command Palette(`Ctrl+Shift+P`)에서 **MCP: Add Server**를 실행하고 서버 정보를 입력합니다. 또는 `.vscode/mcp.json` 파일을 직접 생성합니다:

```json
{
"servers": {
"finance-tools": {
"command": "python",
"args": ["./server.py"],
"cwd": "/절대/경로/my-mcp-server"
}
}
}
```

Cursor의 경우 Settings → MCP에서 서버를 추가할 수 있습니다.

## Step 7: HTTP 전송 방식으로 배포하기

로컬이 아닌 원격 환경에서 MCP 서버를 운영하려면, HTTP 전송 방식을 사용합니다.

```python
if __name__ == "__main__":
mcp.run(transport="http", host="0.0.0.0", port=8000)
```

이렇게 하면 `http://localhost:8000/mcp` 엔드포인트가 생성됩니다. 프로덕션 환경에서는 Nginx나 Caddy 같은 리버스 프록시 뒤에서 HTTPS를 적용하는 것이 권장됩니다.

## 트러블슈팅

MCP 서버 개발 시 자주 만나는 문제와 해결법을 정리합니다.

**서버가 연결되지 않는 경우:** STDIO 기반 서버에서는 `print()`나 `console.log()`를 사용하면 안 됩니다. 표준 출력(stdout)에 쓰면 JSON-RPC 메시지가 깨집니다. 디버깅 로그는 `stderr`로 보내야 합니다.

```python
import sys
print("디버그 메시지", file=sys.stderr) # 안전
```

**도구가 표시되지 않는 경우:** `@mcp.tool` 데코레이터가 빠지지 않았는지, 서버 빌드(`npm run build` for TypeScript)를 했는지 확인합니다.

**MCP Inspector로 디버깅:** FastMCP에 내장된 Inspector를 사용하면 브라우저에서 도구를 테스트할 수 있습니다.

```bash
fastmcp dev server.py
# 브라우저에서 http://127.0.0.1:6274 접속
```

Inspector UI에서 Tools, Resources, Prompts 탭을 통해 각 기능을 개별적으로 테스트할 수 있습니다.

## 완성 코드 전체

```python
from fastmcp import FastMCP
import httpx
import json
from datetime import datetime

mcp = FastMCP("Finance Tools")

# === Tools ===

@mcp.tool
def get_exchange_rate(base: str = "USD", target: str = "KRW") -> dict:
"""실시간 환율 정보를 조회합니다.

Args:
base: 기준 통화 코드 (예: USD, EUR, JPY)
target: 대상 통화 코드 (예: KRW, USD, EUR)
"""
url = f"https://api.exchangerate-api.com/v4/latest/{base}"
response = httpx.get(url, timeout=10)
data = response.json()
rate = data["rates"].get(target)
if rate is None:
return {"error": f"통화 코드 '{target}'을 찾을 수 없습니다."}
return {
"base": base,
"target": target,
"rate": rate,
"updated": data.get("date", str(datetime.now().date()))
}

@mcp.tool
def calculate_exchange(
amount: float, base: str = "USD", target: str = "KRW"
) -> dict:
"""금액을 환전 계산합니다.

Args:
amount: 환전할 금액
base: 원래 통화 코드
target: 변환할 통화 코드
"""
rate_info = get_exchange_rate(base, target)
if "error" in rate_info:
return rate_info
converted = round(amount * rate_info["rate"], 2)
return {
"original": f"{amount} {base}",
"converted": f"{converted} {target}",
"rate": rate_info["rate"]
}

# === Resources ===

@mcp.resource("config://app/settings")
def app_settings() -> str:
"""애플리케이션 설정 정보를 제공합니다."""
return json.dumps({
"version": "1.0.0",
"supported_currencies": ["USD", "KRW", "EUR", "JPY", "GBP", "CNY"],
"api_source": "exchangerate-api.com"
})

@mcp.resource("guide://{topic}")
def usage_guide(topic: str) -> str:
"""사용 가이드를 제공합니다."""
guides = {
"exchange": "환율 조회: get_exchange_rate(base='USD', target='KRW')",
"calculate": "환전 계산: calculate_exchange(amount=100, base='USD', target='KRW')"
}
return guides.get(topic, f"'{topic}' 주제의 가이드가 없습니다.")

# === Run ===

if __name__ == "__main__":
mcp.run()
```

## 마무리

이 가이드에서 다룬 내용을 정리합니다. FastMCP를 사용하여 Python 함수에 데코레이터를 붙이는 것만으로 MCP 서버를 만들 수 있습니다. Tools, Resources, Prompts 세 가지 핵심 기능을 조합하면 다양한 AI 도구를 구축할 수 있고, Claude Desktop, VS Code, Cursor 등 주요 클라이언트에 바로 연결할 수 있습니다.

다음 단계로는 데이터베이스 연동(SQLite, PostgreSQL), OAuth 인증 추가, Docker 컨테이너화를 통한 팀 배포 등을 고려해볼 수 있습니다. FastMCP 3.0에서는 컴포넌트 버전 관리, 세분화된 인증, OpenTelemetry 계측 등 프로덕션 기능도 지원하므로, 엔터프라이즈 환경으로의 확장도 가능합니다.

---
> ⚠️ 이 글은 2026년 2월 16일 기준, MCP 사양 2025-11-25 버전 및 FastMCP 최신 버전 환경에서 작성되었습니다.