Skip to main content
Glama

FastAPI MCP Template

by joonheeu

FastAPI + MCP Template

현대적인 API 서버와 MCP(Model Context Protocol) 통합 템플릿

FastAPI와 MCP를 활용한 프로덕션 수준의 API 서버 템플릿입니다. LLM 통합, 구조화된 로깅, 포괄적인 테스트, 그리고 최고의 개발자 경험을 제공합니다.

Python FastAPI MCP License

✨ 주요 특징

🚀 프로덕션 수준의 API 서버

  • 현대적인 FastAPI: 자동 API 문서화, 타입 안전성, 고성능

  • Scalar 문서화: 아름답고 대화형 API 문서

  • 구조화된 로깅: 색상 지원, 파일 로테이션, 요청 추적

  • 포괄적인 예외 처리: 타입별 커스텀 예외 및 상세한 오류 정보

  • Dependency Injection: FastAPI DI 패턴으로 깔끔한 코드 구조

🤖 MCP 서버 통합

  • FastMCP 구현: 최신 Model Context Protocol 표준

  • SSE 통신: 실시간 Server-Sent Events 연결

  • 도구 및 리소스: LLM이 활용할 수 있는 다양한 도구

  • 확장 가능: 새로운 MCP 기능 쉽게 추가

🛡️ 보안 및 설정

  • 환경별 설정: 개발, 테스트, 프로덕션 환경 지원

  • 보안 기본값: 자동 시크릿 키 생성, CORS 보안 설정

  • 환경변수 관리: .env 파일 지원 및 완전한 설정 검증

🧪 완전한 테스트 커버리지

  • 단위 테스트: MCP 도구 및 API 엔드포인트

  • 통합 테스트: 전체 시스템 엔드투엔드 테스트

  • 동시성 테스트: 멀티스레드 및 성능 테스트

📁 프로젝트 구조

coupang-partners-api/ ├── 🏗️ 소스 코드 │ ├── src/ │ │ ├── core/ # 🔧 핵심 모듈 │ │ │ ├── config.py # ⚙️ 환경별 설정 관리 │ │ │ ├── logging.py # 📝 구조화된 로깅 시스템 │ │ │ ├── exceptions.py # ⚠️ 커스텀 예외 처리 │ │ │ ├── dependencies.py # 🔗 의존성 주입 패턴 │ │ │ ├── database.py # 💾 데이터베이스 추상화 │ │ │ └── models.py # 📋 Pydantic 모델 │ │ ├── api/ # 🌐 FastAPI 애플리케이션 │ │ │ ├── app.py # 🚀 메인 애플리케이션 │ │ │ └── routers/ # 🛣️ API 라우터 │ │ ├── mcp_server/ # 🤖 MCP 서버 │ │ │ ├── server.py # 🖥️ MCP 서버 구현 │ │ │ ├── tools.py # 🔨 MCP 도구 │ │ │ └── resources.py # 📦 MCP 리소스 │ │ └── templates/ # 📄 템플릿 파일 │ ├── 🧪 테스트 │ │ ├── tests/ │ │ │ ├── test_api.py # 🌐 API 테스트 │ │ │ ├── test_mcp.py # 🤖 MCP 테스트 │ │ │ └── test_integration.py # 🔄 통합 테스트 │ ├── 📚 예시 및 문서 │ │ ├── examples/ # 💡 사용 예시 │ │ └── docs/ # 📖 문서 │ └── 🐳 배포 │ ├── Dockerfile # 🐳 Docker 이미지 │ ├── docker-compose.yml # 🐙 Docker Compose │ └── .dockerignore # 🚫 Docker 제외 파일 ├── ⚡ 실행 스크립트 │ ├── run_server.py # 🚀 통합 서버 실행 │ ├── run_api_server.py # 🌐 API 서버 실행 │ ├── run_mcp_server.py # 🤖 MCP 서버 실행 │ └── run_docker.py # 🐳 Docker 실행 도구 ├── 🔧 설정 파일 │ ├── .env.example # 🔑 환경변수 예시 │ ├── .gitignore # 🚫 Git 제외 파일 │ ├── pyproject.toml # 📦 프로젝트 설정 │ └── uv.lock # 🔒 의존성 락 파일 └── 📋 메타데이터 ├── README.md # 📖 이 파일 └── setup_template.py # ⚙️ 템플릿 설정 도구

🚀 빠른 시작

1️⃣ 환경 설정

의존성 설치

# UV 패키지 매니저 사용 (권장) uv sync # 또는 pip 사용 pip install -r requirements.txt # 개발 환경 (테스트, 린팅 도구 포함) pip install -r requirements-dev.txt

환경변수 설정

# 환경변수 파일 복사 및 수정 cp .env.example .env

.env

# 애플리케이션 설정 APP_NAME="My Awesome API" ENVIRONMENT="development" # development, production, test # 보안 설정 SECRET_KEY="your-secure-random-key-here" # CORS 설정 (개발용) CORS_ORIGINS="http://localhost:3000,http://localhost:8080" # 로깅 설정 LOG_LEVEL="INFO" LOG_FILE="logs/app.log"

2️⃣ 서버 실행

🎯 통합 실행 (권장)

# API + MCP 서버 동시 실행 python run_server.py

🔄 개별 실행

# Terminal 1: API 서버 (포트 8000) python run_api_server.py # Terminal 2: MCP 서버 (포트 8001) python run_mcp_server.py

🐳 Docker 실행

# 프로덕션 모드 docker-compose up --build # 개발 모드 (볼륨 마운트) docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build

3️⃣ 접속 확인

서비스

URL

설명

🌐

API 서버

http://localhost:8000

메인 API 엔드포인트

📚

API 문서

http://localhost:8000/docs

대화형 API 문서 (Scalar)

❤️

헬스체크

http://localhost:8000/health

서버 상태 확인

🤖

MCP 서버

http://localhost:8001/sse

MCP SSE 엔드포인트

🛠️ 템플릿 커스터마이징

💡 빠른 설정

# 대화형 CLI로 프로젝트 정보 설정 python setup_template.py --customize

🆕 새 프로젝트 생성

# 새 프로젝트 생성 python setup_template.py --new my-awesome-project # 특정 디렉토리에 생성 python setup_template.py --new my-project --target-dir /path/to/projects

🔄 백업에서 복원

# 원래 템플릿 상태로 복원 python setup_template.py --restore

📚 API 문서

🏥 헬스 체크

GET /health # 종합 헬스 체크 GET /health/simple # 간단한 상태 확인 GET /health/detailed # 상세 시스템 정보

📦 아이템 관리

GET /api/v1/items # 아이템 목록 (페이지네이션) POST /api/v1/items # 아이템 생성 GET /api/v1/items/{id} # 특정 아이템 조회 PUT /api/v1/items/{id} # 아이템 수정 DELETE /api/v1/items/{id} # 아이템 삭제 GET /api/v1/items/search/by-name # 이름으로 검색 GET /api/v1/items/stats/summary # 통계 정보

👥 사용자 관리

GET /api/v1/users # 사용자 목록 POST /api/v1/users # 사용자 생성 GET /api/v1/users/{id} # 특정 사용자 조회 PUT /api/v1/users/{id} # 사용자 수정 DELETE /api/v1/users/{id} # 사용자 삭제

📖 API 사용 예시

아이템 생성

curl -X POST "http://localhost:8000/api/v1/items" \ -H "Content-Type: application/json" \ -d '{ "name": "노트북", "description": "고성능 개발용 노트북", "price": 1200000, "category": "electronics", "is_available": true, "tags": ["laptop", "development"] }'

아이템 검색

curl "http://localhost:8000/api/v1/items?category=electronics&available_only=true&limit=10"

🤖 MCP 서버 기능

🔨 사용 가능한 도구 (Tools)

도구명

설명

매개변수

get_items

아이템 목록 조회

skip

,

limit

,

category

,

available_only

get_item_by_id

ID로 아이템 조회

item_id

create_item

새 아이템 생성

name

,

price

,

description

, etc.

update_item

아이템 수정

item_id

, 수정할 필드들

delete_item

아이템 삭제

item_id

search_items

아이템 검색

query

,

search_field

get_database_stats

데이터베이스 통계

없음

export_database

데이터 내보내기

없음

📦 사용 가능한 리소스 (Resources)

리소스 URI

설명

database://schema

데이터베이스 스키마 정보

docs://api

API 문서 정보

data://items

아이템 데이터

data://users

사용자 데이터

🎯 MCP 사용 예시

MCP 클라이언트에서 도구 호출:

# 아이템 생성 result = await mcp_server.call_tool("create_item", { "name": "새 상품", "price": 50000, "category": "electronics" }) # 아이템 검색 result = await mcp_server.call_tool("search_items", { "query": "노트북", "search_field": "name" })

🧪 테스트

🏃 테스트 실행

# 모든 테스트 실행 pytest # 커버리지 포함 pytest --cov=src --cov-report=html # 특정 테스트 모듈 pytest tests/test_api.py -v # MCP 테스트만 실행 pytest tests/test_mcp.py -v # 통합 테스트만 실행 pytest tests/test_integration.py -v

📊 테스트 커버리지

  • API 엔드포인트: 모든 CRUD 작업 및 오류 시나리오

  • MCP 도구: 모든 도구 기능 및 오류 처리

  • 통합 테스트: API ↔ MCP 데이터 일관성

  • 동시성 테스트: 멀티스레드 환경에서의 안정성

  • 시스템 한계 테스트: 대용량 데이터 및 극한 상황

🎯 테스트 예시

# 개발용 빠른 테스트 pytest tests/ -k "not integration" --tb=short # CI/CD용 전체 테스트 pytest tests/ --cov=src --cov-report=xml --junitxml=test-results.xml

🚀 배포

🐳 Docker 배포

프로덕션 빌드

# 이미지 빌드 docker build -t my-awesome-api . # 컨테이너 실행 docker run -p 8000:8000 -p 8001:8001 my-awesome-api

Docker Compose

# 프로덕션 환경 docker-compose up --build -d # 로그 확인 docker-compose logs -f # 서비스 중지 docker-compose down

☁️ 클라우드 배포

Heroku

# Heroku CLI 로그인 heroku login # 앱 생성 heroku create my-awesome-api # 환경변수 설정 heroku config:set SECRET_KEY="your-secret-key" heroku config:set ENVIRONMENT="production" # 배포 git push heroku main

AWS ECS / Azure Container Instances

# 환경변수 설정 예시 export SECRET_KEY="your-production-secret-key" export ENVIRONMENT="production" export CORS_ORIGINS="https://yourdomain.com" # 컨테이너 실행 docker run -p 8000:8000 -p 8001:8001 \ -e SECRET_KEY=$SECRET_KEY \ -e ENVIRONMENT=$ENVIRONMENT \ -e CORS_ORIGINS=$CORS_ORIGINS \ my-awesome-api

📊 프로덕션 모니터링

환경변수 설정:

# 로깅 설정 LOG_LEVEL="WARNING" LOG_FILE="/var/log/app/app.log" # 보안 설정 SECRET_KEY="강력한-랜덤-키-32자-이상" CORS_ORIGINS="https://yourdomain.com,https://admin.yourdomain.com" # 성능 설정 DATABASE_URL="postgresql://user:pass@host:5432/dbname"

🔧 개발 가이드

📝 새 API 엔드포인트 추가

  1. 모델 정의 (src/core/models.py):

class NewModel(BaseEntity): name: str = Field(..., description="이름") value: int = Field(..., description="값")
  1. 라우터 생성 (src/api/routers/new_router.py):

from fastapi import APIRouter, Depends from ...core.dependencies import get_database from ...core.models import NewModel router = APIRouter() @router.get("/items", response_model=List[NewModel]) async def get_items(db: InMemoryDatabase = Depends(get_database)): return db.find_all("new_items")
  1. 앱에 등록 (src/api/app.py):

from .routers import new_router app.include_router(new_router.router, prefix="/api/v1", tags=["New Items"])

🔨 새 MCP 도구 추가

  1. 도구 정의 (src/mcp_server/tools.py):

@mcp.tool() def new_tool(context: Context, param1: str, param2: int = 10) -> dict: """새로운 MCP 도구""" try: # 비즈니스 로직 result = process_data(param1, param2) return {"success": True, "result": result} except Exception as e: logger.error(f"Tool error: {e}") return {"success": False, "error": str(e)}
  1. 리소스 추가 (src/mcp_server/resources.py):

@mcp.resource("data://new_resource") def get_new_resource(context: Context) -> str: """새로운 MCP 리소스""" return json.dumps({"data": "new_resource_data"})

🧪 테스트 작성

  1. 단위 테스트:

@pytest.mark.asyncio async def test_new_tool(): result = await mcp_server.call_tool("new_tool", { "param1": "test", "param2": 5 }, mock_context) assert result["success"] == True
  1. 통합 테스트:

def test_new_endpoint(client): response = client.post("/api/v1/new-items", json={ "name": "Test Item", "value": 100 }) assert response.status_code == 201

📋 코딩 스타일

  • 타입 힌트: 모든 함수에 타입 힌트 사용

  • Docstring: Google 스타일 docstring 사용

  • 로깅: 구조화된 로깅 (logger.info(), logger.error())

  • 예외 처리: 커스텀 예외 클래스 사용

  • 의존성 주입: FastAPI Depends() 패턴 활용

🔍 문제 해결

🚨 일반적인 문제들

포트 충돌

# 포트 사용 확인 lsof -i :8000 lsof -i :8001 # 프로세스 종료 kill -9 <PID>

환경변수 설정 오류

# 환경변수 확인 python -c "from src.core.config import settings; print(settings.dict())" # .env 파일 확인 cat .env

의존성 문제

# 의존성 재설치 uv sync --refresh # 캐시 정리 uv cache clean

로그 확인

# 애플리케이션 로그 tail -f logs/app.log # Docker 로그 docker-compose logs -f

🔧 디버깅 팁

  1. DEBUG 모드 활성화:

export DEBUG=true export LOG_LEVEL=DEBUG
  1. 개발 서버에서 실행:

uvicorn src.api.app:create_app --factory --reload --log-level debug
  1. MCP 서버 단독 테스트:

python -m src.mcp_server.server

🤝 기여하기

🔄 기여 워크플로우

  1. Fork 저장소

  2. Feature 브랜치 생성: git checkout -b feature/amazing-feature

  3. 커밋: git commit -m 'Add amazing feature'

  4. 푸시: git push origin feature/amazing-feature

  5. Pull Request 생성

📋 기여 가이드라인

  • 코드 스타일: Black, isort, flake8 사용

  • 테스트: 새 기능에 대한 테스트 추가

  • 문서화: Docstring 및 README 업데이트

  • 커밋 메시지: Conventional Commits 스타일 사용

🛠️ 개발 환경 설정

# 개발 의존성 설치 uv sync --dev # pre-commit 훅 설치 pre-commit install # 코드 포맷팅 black src/ tests/ isort src/ tests/ # 린팅 flake8 src/ tests/ mypy src/

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

🙏 감사의 말

  • FastAPI - 현대적인 Python 웹 프레임워크

  • FastMCP - Model Context Protocol 구현

  • Pydantic - 데이터 검증 및 설정 관리

  • UV - 빠른 Python 패키지 매니저


Related MCP Servers

  • -
    security
    A
    license
    -
    quality
    A high-performance FastAPI server supporting Model Context Protocol (MCP) for seamless integration with Large Language Models, featuring REST, GraphQL, and WebSocket APIs, along with real-time monitoring and vector search capabilities.
    Last updated -
    9
    MIT License
  • -
    security
    F
    license
    -
    quality
    A production-ready MCP server built with FastAPI, providing an enhanced tool registry for creating, managing, and documenting AI tools for Large Language Models (LLMs).
    Last updated -
    34
  • -
    security
    A
    license
    -
    quality
    A Model Context Protocol (MCP) server that implements AI-First Development framework principles, allowing LLMs to interact with context-first documentation tools and workflows for preserving knowledge and intent alongside code.
    Last updated -
    338
    AGPL 3.0
  • -
    security
    F
    license
    -
    quality
    A demonstration server that automatically generates Model Context Protocol (MCP) servers from OpenAPI specifications, providing seamless integration with FastAPI and supporting various transmission methods like STDIO, HTTP, and SSE.
    Last updated -
    • Apple
    • Linux

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joonheeu/fastapi-mcp-template'

If you have feedback or need assistance with the MCP directory API, please join our Discord server