AI 原生开放教材

外观

FastCampus AI Agent 바이브코딩 강의系统课程·英文原文 ↗原件 ↓仓库 ↗

서울시 문화행사 MCP Server - 구현 요약 ​

프로젝트 개요 ​

PLAN.md를 바탕으로 서울시 문화행사 정보를 제공하는 MCP 서버를 성공적으로 구현했습니다.

구현된 구성 요소 ​

1. 프로젝트 구조 ​

seoul-culture-mcp/
├── pyproject.toml              # uv 프로젝트 설정
├── README.md                   # 영문 문서 (Claude Desktop 사용자용)
├── .env.example                # 환경변수 템플릿
├── src/
│   └── seoul_culture_mcp/
│       ├── __init__.py         # 패키지 초기화
│       ├── server.py           # MCP 서버 (1개 Tool, 3개 Resources)
│       ├── api_client.py       # 서울시 API 클라이언트
│       └── models.py           # Pydantic 데이터 모델
├── test_api.py                 # API 통합 테스트
├── test_mcp.py                 # MCP 도구 테스트
└── verify_setup.py             # 설정 검증 스크립트

2. 핵심 파일 ​

src/seoul_culture_mcp/api_client.py ​

  • SeoulCultureAPIClient 클래스 구현
  • 서울시 API URL 생성 (_build_url)
  • 비동기 HTTP 요청 처리 (search_events)
  • 한글 파라미터 URL 인코딩 지원
  • 에러 핸들링 (HTTP 오류, 네트워크 오류)

src/seoul_culture_mcp/models.py ​

  • CulturalEvent: 문화행사 데이터 모델
  • APIResponse: API 응답 모델
  • Pydantic 기반 타입 검증

src/seoul_culture_mcp/server.py ​

MCP Tool (1개):

  • search_cultural_events: 서울시 문화행사 검색
    • 파라미터: start_index, end_index, codename, title, date
    • 반환: JSON 형식의 문화행사 목록
    • 검증: 1000건 제한, 에러 처리

MCP Resources (3개):

  • seoul://culture/api-info: API 메타정보
  • seoul://culture/categories: 행사 카테고리 목록
  • seoul://culture/districts: 서울시 25개 자치구 목록

3. 의존성 ​

  • fastmcp (>=2.0.0): MCP 서버 프레임워크
  • httpx (>=0.27.0): 비동기 HTTP 클라이언트
  • pydantic (>=2.0.0): 데이터 검증
  • python-dotenv (>=1.0.0): 환경변수 관리

테스트 결과 ​

API 테스트 ​

✅ 서울시 API 연동 성공 ✅ 샘플 키로 5개 행사 조회 확인 ✅ 응답 파싱 정상 작동 ✅ 다음 데이터 확인:

  • K-핸드메이드페어 2025 (전시/미술)
  • 카즈미 타테이시 트리오 내한공연 (콘서트)
  • M 아티스트 2025 바리톤 박주성 리사이틀 (클래식)
  • 연극 [코다] (연극)
  • M발레시리즈 (무용)

MCP 서버 검증 ​

✅ MCP 서버 초기화 성공 ✅ 서버 이름: "Seoul Cultural Events" ✅ 도구 및 리소스 등록 완료

Claude Desktop 연동 방법 ​

1. 설정 파일 위치 ​

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 최종 작동 설정 ​

json
{
  "mcpServers": {
    "seoul-culture": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/bong/github/fastcampus-lecture/Part5_AI_Agent_프로젝트_3개/Chapter2_바이브코딩으로_서울시_문화행사_조회하는_MCP_SERVER_만들기",
        "run",
        "python",
        "run_server.py"
      ],
      "env": {
        "SEOUL_API_KEY": "6278434658626f6e3933624c4e5078"
      }
    }
  }
}

핵심 포인트:

  • --directory 플래그로 프로젝트 경로 명시
  • run_server.py 스크립트가 Python 경로 자동 설정
  • cwd 대신 --directory 사용 (더 안정적)

3. API 키 발급 ​

  1. 서울 열린데이터광장 방문
  2. 회원가입 및 로그인
  3. 인증키 신청
  4. 발급된 키를 SEOUL_API_KEY에 설정

4. Claude에서 사용 예시 ​

  • "이번 주말에 열리는 전시회 알려줘"
  • "12월에 열리는 콘서트 정보 찾아줘"
  • "강남구에서 열리는 무료 문화행사 알려줘"
  • "지브리 전시회 정보 찾아줘"

구현 특징 ​

장점 ​

  1. 단순하고 명확한 API: 서울시 API는 1개의 엔드포인트만 제공하므로 래핑이 단순
  2. 유연한 검색: 분류, 제목, 날짜별 다양한 조합 검색 가능
  3. 비동기 처리: httpx를 사용한 효율적인 HTTP 요청
  4. 타입 안전성: Pydantic을 통한 데이터 검증
  5. 에러 핸들링: API 오류, 네트워크 오류 등 다양한 상황 처리

API 제약사항 ​

  • 한 번에 최대 1000건까지만 조회 가능
  • 샘플키는 최대 5건까지만 조회 가능
  • 매일 1회 데이터 업데이트
  • 인증키 필요

향후 개선 사항 ​

  1. 응답 필터링: 클라이언트 측에서 자치구별 필터링 기능 추가
  2. 날짜 범위 검색: 특정 기간의 행사를 조회하는 헬퍼 함수
  3. 캐싱: 자주 조회되는 데이터에 대한 로컬 캐싱
  4. 배치 조회: 1000건 이상의 데이터를 자동으로 여러 번 나누어 조회
  5. 테스트 강화: pytest를 사용한 단위 테스트 및 통합 테스트 추가

참고 문서 ​

결론 ​

PLAN.md의 모든 요구사항을 성공적으로 구현했습니다:

  • ✅ Phase 1: 프로젝트 설정
  • ✅ Phase 2: API Client 구현
  • ✅ Phase 3: MCP Server 구현
  • ✅ Phase 4: 테스트 및 검증
  • ✅ Phase 5: 문서화

이제 Claude Desktop에 연결하여 실제로 사용할 수 있습니다!