FastMCP 배우기 - MCP 서버 예제

Model Context Protocol (MCP) 서버를 FastMCP로 구축하는 방법을 배우는 학습 프로젝트입니다. FastMCP는 MCP 호환 도구와 리소스를 만들기 위한 Python 프레임워크입니다.

이 프로젝트에 대하여

이 저장소에는 두 개의 완전한 MCP 서버 구현이 포함되어 있습니다:

• 데모 서버 - FastMCP 기초를 배우기 위한 간단한 예제

• 지출 추적기 - 완전한 기능을 갖춘 실제 애플리케이션

Claude, 다른 AI 모델 또는 사용자 정의 애플리케이션과 함께 사용할 수 있는 MCP 서버를 구축하는 방법을 이해하는 데 적합합니다.

Related MCP server: expense-tracker-mcp-server

📋 서버 1: 데모 서버 (main.py)

기본 도구가 포함된 간단한 입문용 MCP 서버입니다.

도구

roll_dice(n_dice: int) -> list[int]

6면체 주사위 n개를 굴려 결과를 반환합니다.

roll_dice(3) → [4, 2, 6]

add_numbers(a: float, b: float) -> float

두 숫자를 더하고 합계를 반환합니다.

add_numbers(5, 3) → 8

데모 서버 실행

python main.py

💰 서버 2: 지출 추적기 (test.py)

데이터베이스 영속성, 분류, 고급 필터링을 갖춘 종합적인 지출 관리 MCP 서버입니다.

기능

• 영구 저장을 위한 SQLite 데이터베이스

• 계층적 카테고리 시스템 (상위 카테고리 + 하위 카테고리)

• 날짜 범위 필터링

• 카테고리별 지출 요약

• CRUD 작업 (생성, 읽기, 업데이트, 삭제)

• 카테고리 병합/이름 변경

데이터 구조

각 지출 항목에는 다음이 포함됩니다:

• id - 고유 식별자 (자동 증가)

• date - 지출 날짜 (문자열 형식)

• amount - 숫자 값으로 표시된 지출 금액

• category - 상위 카테고리 (categories.json에서 가져옴)

• subcategory - 세부 추적을 위한 선택적 하위 카테고리

• note - 선택적 설명/메모

사용 가능한 카테고리

지출 추적기는 각각 여러 하위 카테고리를 가진 12개의 상위 카테고리를 지원합니다:

• 식비 - 식료품, 외식, 커피 등

• 교통 - 연료, 대중교통, 택시/차량 호출, 주차, 통행료

• 주거 - 임대료, 유지보수, 재산세, 수리, 가구

• 공과금 - 전기, 수도, 가스, 인터넷, 모바일, TV

• 건강 - 의약품, 의사 상담, 진단, 피트니스

• 교육 - 도서, 강좌, 온라인 구독, 시험 수수료

• 가족 및 자녀 - 학비, 어린이집, 장난감, 행사

• 엔터테인먼트 - 영화, 스트리밍 구독, 게임, 외출

• 쇼핑 - 의류, 신발, 전자제품, 가전제품, 홈 데코

• 구독 - SaaS 도구, 클라우드/AI, 음악, 저장소, 뉴스레터

• 개인 관리 - 미용실, 그루밍, 화장품, 위생

• 선물 및 기부 - 개인 선물, 자선, 명절 선물

• 금융 및 수수료 - 은행 수수료, 투자 수수료 등

도구

add_expense(date: str, amount: int, category: str, subcategory: str = "", note: str = "")

데이터베이스에 새 지출 항목을 추가합니다.

{
  "date": "2026-08-20",
  "amount": 45,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch with friends"
}

반환: {"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

포함 날짜 범위(YYYY-MM-DD 형식) 내의 모든 지출을 나열합니다.

list_expenses("2026-08-01", "2026-08-31")

모든 필드가 포함된 지출 기록 배열을 반환합니다.

summarize(start_date: str, end_date: str, category: str = None)

날짜 범위 내에서 카테고리별 총 지출 금액을 가져옵니다. 선택적으로 특정 카테고리로 필터링할 수 있습니다.

summarize("2026-08-01", "2026-08-31")
summarize("2026-08-01", "2026-08-31", "food")

반환:

[
  {"category": "food", "total_amount": 150},
  {"category": "transport", "total_amount": 50}
]

update_expense(id: int, date: str = None, amount: float = None, category: str = None, subcategory: str = None, note: str = None)

기존 지출의 특정 필드를 업데이트합니다. 제공된 필드만 수정됩니다.

update_expense(1, amount=50, note="Updated note")

반환: {"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

id로 지출 항목을 삭제합니다.

delete_expense(1)

반환: {"status": "ok", "deleted_id": 1}

merge_categories(old_categories: list[str], new_category: str)

하나 이상의 카테고리 레이블을 단일 새 카테고리로 이름을 바꾸거나 병합합니다. 지출 카테고리를 통합하는 데 유용합니다.

merge_categories(["food", "dining"], "meals")

반환: {"status": "ok", "rows_updated": 15, "new_category": "meals"}

리소스

expense://categories

카테고리 구조를 JSON으로 반환합니다. 이 리소스는 매번 새로 읽으므로 서버를 다시 시작하지 않고도 categories.json을 편집할 수 있습니다.

지출 추적기 실행

python test.py

데이터베이스: 영구 저장을 위해 같은 디렉토리에 expenses.db를 생성합니다.

설치 및 설정

사전 요구 사항

• Python 3.14+

• FastMCP 3.4.7+

종속성 설치

pip install fastmcp>=3.4.7

또는 프로젝트의 pyproject.toml 사용:

pip install -e .

프로젝트 구조

learn-fastmcp/
├── main.py              # Demo server (roll_dice, add_numbers)
├── test.py              # Expense Tracker server (full MCP implementation)
├── categories.json      # Category definitions for expense tracker
├── expenses.db          # SQLite database (auto-created by test.py)
├── pyproject.toml       # Project configuration
└── README.md            # This file

학습 경로

1. main.py로 시작하여 기본 사항을 이해합니다:

   • FastMCP 인스턴스 생성 방법

   • @mcp.tool 데코레이터로 간단한 도구 정의 방법

   • mcp.run()으로 서버 실행 방법

2. test.py로 진행하여 고급 패턴을 배웁니다:

   • SQLite 데이터베이스 통합

   • 파일 I/O 및 리소스 관리

   • 복잡한 도구 로직 (CRUD 작업)

   • @mcp.resource 데코레이터를 사용한 리소스

   • 선택적 및 조건부 매개변수

   • 오류 처리 및 검증

주요 FastMCP 개념

도구

@mcp.tool()로 데코레이트된 함수로, MCP 클라이언트가 호출할 수 있습니다. 각 도구에는 다음이 있습니다:

• 유형 힌트가 있는 입력 매개변수

• 기능을 설명하는 docstring

• 반환 값

리소스

URI를 통해 접근 가능한 정적 또는 동적 콘텐츠입니다. @mcp.resource()로 정의됩니다:

• 고유 URI로 식별 (예: expense://categories)

• 선택적으로 MIME 유형 지정

• 파일에서 읽거나 동적으로 계산 가능

서버 수명 주기

mcp = FastMCP("ServerName")  # Create instance

@mcp.tool()                  # Define tools
def my_tool(): ...

if __name__ == "__main__":
    mcp.run()               # Start the server

다음 단계

• 데모 서버를 수정하여 새 도구 추가

• 지출 추적기에 새 기능 확장 (예: 예산, 반복 지출)

• 관심 있는 도메인에 대한 자체 MCP 서버 만들기

• MCP 프로토콜을 사용하여 MCP 서버를 Claude에 연결

리소스

• MCP 문서

• FastMCP GitHub

• Python 타이핑 문서

즐겁게 배우세요! 🚀