🐍 Python SDK와 UV로 MCP 서버 만들기 실습기: 동토 vs 트랄라레오의 전투까지 ⚔️

🐍 Python SDK와 UV로 MCP 서버 만들기 실습기: 동토 vs 트랄라레오의 전투까지 ⚔️

소개

토요일 실습으로 Python SDK를 이용해 MCP 서버 개발을 직접 따라 해봤어요. 최근 Python 생태계에서 화제가 되고 있는 빠른 프로젝트 매니저 uv를 활용해 환경 구성도 해봤고요. 실습은 단순한 코드 따라하기가 아니라, LLM이 만든 가상의 캐릭터 데이터를 MCP 서버에 연결해 실제 툴처럼 작동시키는 경험까지 이어졌습니다 😎

그리고 마지막엔 Claude Desktop에서 캐릭터 전투를 시뮬레이션했는데… 제가 만든 캐릭터 동토가 트랄라레오를 이겼습니다! 😂

진행 방법

🧰 1. UV 설치 및 환경 구성

uv란?

• Rust 기반 초고속 Python 프로젝트 매니저

• ruff를 만든 Astral에서 개발한 도구로, venv + 패키지 관리 + 실행까지 지원합니다 💨

💻 설치 방법

• macOS (Homebrew)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install uv

• Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

⚙️ 프로젝트 생성

uv init my-mcp-server
cd my-mcp-server
uv venv

• 가상환경 활성화:

  • macOS: source .venv/bin/activate

  • Windows: .venv\Scripts\activate

📦 필수 라이브러리 설치

uv add fastmcp

🛠️ 2. Windsurf로 프로젝트 개발하기

1. Windsurf 실행 후 File > Open Folder 선택

2. 터미널 열고 가상환경 활성화

🧪 3. MCP 서버 기본 기능 구현

main.py 파일 작성:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool()
def echo_tool(message: str) -> str:
    return f"Tool echo: {message}"

if __name__ == "__main__":
    mcp.run(transport='stdio')

✅ 테스트

fastmcp dev main.py

• 웹 브라우저에서 http://127.0.0.1:6274 접속 → STDIO 연결 → echo_tool 테스트

🧠 4. 캐릭터 데이터 연동 및 툴 추가

📁 데이터 폴더 및 CSV 생성

• data/char_info.csv 생성 (내용은 Claude에게 생성 요청)

• 예시:

name,information
동토,"차가운 눈보라를 다루는 마법사"
트랄라레오,"노래로 적을 무장해제시키는 전사"

🧬 툴 함수 추가

import csv, os

data_path = os.path.join(os.path.dirname(__file__), 'data', 'char_info.csv')

@mcp.tool()
def get_character_info(name: str) -> str:
    with open(data_path, newline='', encoding='utf-8') as f:
        reader = csv.DictReader(f)
        for row in reader:
            if row['name'] == name:
                return row['information']
    return "캐릭터 정보를 찾을 수 없습니다."

🔄 상대경로 처리 이유

• MCP Host에서 실행 시 절대경로 사용 시 에러 발생
  → Python 파일 기준 상대경로로 수정

🖥️ 5. Claude Desktop 연동

MCP 설치 및 실행

fastmcp install main.py

• Claude Desktop 재실행 후 툴 인식

ALT

Adobe Flash Player의 한국 버전 스크린 샷

🧪 테스트 예시

echo_tool:

안녕하세요 → "Tool echo: 안녕하세요"

get_character_info:

"동토", "트랄라레오" → 두 캐릭터 소개 + 전투 시뮬레이션
승자는… 동토! 🧊❄️💥

승부예측

dong-to랑 트랄라레오랑 싸우면 누가 이겨?

ALT

검은 색 화면에 한국 이모티콘 스크린 샷

ALT

한국 단어 목록의 스크린 샷

ALT

한국 버전의 게임 스크린 샷

결과와 배운 점

👍 좋았던 점

• uv 덕분에 환경 설정이 매우 빠르고 간편했음

• MCP SDK가 구조적으로 잘 짜여 있어 확장하기 쉬움

• Claude Desktop에서 직접 툴 테스트까지 가능해 개발 몰입도가 높았음

😵‍💫 어려웠던 점

• CSV 상대경로 설정에서 삽질 (하지만 덕분에 Python 경로 다루는 법 숙지!)

• LLM이 생성한 데이터가 잘못될 경우 툴 결과에 영향 → 데이터 신뢰도 주의 필요

• 가상환경 구축 경로를 잘 맞출 필요가 있음

🧠 느낀 점

"실습이었지만 진짜 내 툴을 만든 기분".
단순히 따라 하는 것이 아니라, 내가 직접 만든 데이터를 바탕으로 서버를 띄우고 툴로 불러와 시뮬레이션까지 진행하면서 개발자 감성 제대로 충전됐습니다.
SDK + UV + Claude 조합은 추천하고 싶어요! 🔥

도움 받은 글

• Claude 관련 예시 프롬프트 및 실습 자료