초보자를 위한 MCP 서버 설정 완벽 가이드: Python으로 날씨 API 서버 구축하기

초보자를 위한 MCP 서버 설정 완벽 가이드: Python으로 날씨 API 서버 구축하기

대형 언어 모델(LLM)과 외부 데이터 소스를 연결하는 Model Context Protocol(MCP)을 활용하면, Claude와 같은 AI 모델이 실시간 데이터에 접근할 수 있습니다. 이 글에서는 Python을 사용하여 날씨 정보를 제공하는 MCP 서버를 설정하는 방법을 단계별로 설명합니다.

목차

• MCP란 무엇인가?
• 사전 요구사항
• 단계별 MCP 서버 설정 가이드
  • 환경 설정하기
  • 날씨 서버 코드 작성하기
  • 서버 실행하기
  • Claude for Desktop과 연동하기
• 문제 해결 가이드
• MCP 서버 활용 확장 방안
• 자주 묻는 질문

MCP란 무엇인가?

Model Context Protocol(MCP)은 대형 언어 모델이 외부 데이터 소스와 도구에 접근할 수 있게 해주는 개방형 표준입니다. 쉽게 말해 USB-C 포트처럼 AI 모델이 다양한 데이터 소스와 연결될 수 있도록 표준화된 인터페이스를 제공합니다.

MCP를 통해 Claude와 같은 AI 모델은:

• 실시간 날씨 데이터 조회
• 특정 데이터베이스 검색
• 외부 API와 상호작용
• 사용자 정의 도구 활용

등의 작업을 수행할 수 있습니다.

사전 요구사항

MCP 서버 설정을 시작하기 전에 다음 항목을 준비해야 합니다:

• Python 3.10 이상 설치 (최신 버전 권장)
• 기본적인 Python 프로그래밍 지식
• 명령줄 인터페이스(터미널/커맨드 프롬프트) 사용 경험
• 인터넷 연결 (패키지 설치 및 날씨 API 접근용)

단계별 MCP 서버 설정 가이드

1. 환경 설정하기

먼저 uv라는 빠른 Python 패키지 관리자를 설치하여 효율적인 개발 환경을 구축합니다.

# uv 패키지 관리자 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 디렉토리 생성 및 설정
uv init weather
cd weather
uv venv

# 가상 환경 활성화 (운영체제에 맞는 명령어 사용)
source .venv/bin/activate  # Linux/macOS
# 또는
.venv\Scripts\activate     # Windows

# 필요한 패키지 설치
uv add "mcp[cli]" httpx

# 서버 코드 파일 생성
touch weather.py  # Linux/macOS
# 또는
type nul > weather.py  # Windows

2. 날씨 서버 코드 작성하기

weather.py 파일을 열고 다음 코드를 작성합니다:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

async def make_nws_request(endpoint: str) -> dict[str, Any]:
    """National Weather Service API에 요청을 보내는 헬퍼 함수"""
    url = f"{NWS_API_BASE}{endpoint}"
    headers = {"User-Agent": USER_AGENT}
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers, timeout=30.0)
        response.raise_for_status()
        return response.json()

def format_alert(alert: dict[str, Any]) -> str:
    """날씨 경보 정보를 포맷팅하는 함수"""
    return f"{alert['properties']['event']} - {alert['properties']['headline']}"

@mcp.tool()
async def get_alerts(state: str) -> str:
    """주어진 주 코드(예: CA, NY)에 대한 활성 날씨 경보를 가져옵니다."""
    endpoint = f"/alerts/active?area={state}"
    data = await make_nws_request(endpoint)
    alerts = data.get("features", [])
    if not alerts:
        return f"{state}에 대한 활성 경보가 없습니다."
    formatted_alerts = [format_alert(alert) for alert in alerts]
    return "\n".join(formatted_alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """주어진 위도와 경도에 대한 날씨 예보를 가져옵니다. 다음 5개 기간을 표시합니다."""
    endpoint = f"/points/{latitude},{longitude}"
    point_data = await make_nws_request(endpoint)
    forecast_url = point_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url.replace(NWS_API_BASE, ""))
    periods = forecast_data["properties"]["periods"][:5]
    forecast = "\n".join([f"{p['name']}: {p['detailedForecast']}" for p in periods])
    return forecast

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

이 코드는 다음과 같은 기능을 제공합니다:

함수 설명 입력 출력

get_alerts	특정 주의 활성 날씨 경보 조회	주 코드(예: CA, NY)	활성 경보 목록
get_forecast	특정 위치의 날씨 예보 조회	위도와 경도	5개 기간의 상세 예보

3. 서버 실행하기

터미널에서 다음 명령어로 서버를 실행합니다:

uv run weather.py

서버가 실행되면 콘솔에 별도의 출력이 표시되지 않지만, stdio 전송 방식으로 동작하며 Claude와 같은 MCP 클라이언트의 요청을 기다립니다.

4. Claude for Desktop과 연동하기

Claude for Desktop에서 MCP 서버를 사용하려면 다음 단계를 따르세요:

1. Claude for Desktop을 다운로드하고 설치합니다.
2. Claude 구성 파일을 편집합니다. 파일 위치는 운영체제에 따라 다릅니다:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. 구성 파일에 날씨 서버를 추가합니다:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/절대/경로/weather", "run", "weather.py"]
    }
  }
}

중요: /절대/경로/weather 부분을 여러분의 프로젝트 디렉토리 절대 경로로 바꾸세요. 경로에 공백이 있는 경우 따옴표로 감싸지 마세요.

1. Claude for Desktop을 재시작합니다.
2. Claude와 대화하면서 날씨 정보를 요청할 수 있습니다. 예를 들어:
   • "캘리포니아의 현재 날씨 경보를 알려줘"
   • "샌프란시스코(위도 37.7749, 경도 -122.4194)의 날씨 예보를 보여줘"

문제 해결 가이드

MCP 서버 설정 중 문제가 발생할 경우 다음 단계를 확인하세요:

문제 해결 방법

패키지 설치 오류	Python 버전이 3.10 이상인지 확인하고, 가상 환경이 활성화되었는지 확인
서버 실행 오류	weather.py 코드에 오타가 없는지 확인하고, 필요한 패키지가 모두 설치되었는지 확인
Claude 연결 오류	구성 파일의 경로가 정확한 절대 경로인지 확인하고, Claude for Desktop이 재시작되었는지 확인
API 응답 오류	인터넷 연결을 확인하고, NWS API가 정상 작동하는지 확인

고급 디버깅이 필요한 경우 MCP 디버깅 가이드를 참조하세요.

MCP 서버 활용 확장 방안

날씨 서버 외에도 MCP를 활용하여 다양한 데이터 소스에 접근할 수 있습니다:

1. GitHub 통합: 저장소 정보, 이슈, PR 등을 조회하는 도구
2. Google Drive 통합: 문서 검색 및 내용 조회
3. 데이터베이스 쿼리: SQL 쿼리를 실행하여 데이터 조회
4. 번역 서비스: 실시간 텍스트 번역 기능
5. 뉴스 API: 최신 뉴스 헤드라인 및 내용 조회

각 통합에는 해당 서비스의 API 키가 필요할 수 있으며, 필요한 경우 인증 과정을 추가해야 합니다.

자주 묻는 질문

Q: MCP 서버를 원격으로 호스팅할 수 있나요?

A: 네, 원격 서버에 호스팅할 수 있습니다. 이 경우 stdio 대신 HTTP/WebSocket 전송을 사용하고, 적절한 인증 및 보안 설정을 추가해야 합니다.

Q: 여러 MCP 서버를 동시에 사용할 수 있나요?

A: 네, Claude for Desktop 구성 파일에 여러 서버를 추가하여 동시에 사용할 수 있습니다.

Q: 국내 날씨 데이터를 사용할 수 있나요?

A: 네, 코드를 수정하여 기상청이나 다른 국내 날씨 API를 사용할 수 있습니다. API 문서를 참조하여 엔드포인트와 응답 형식을 적절히 조정하세요.

Q: Python 이외의 언어로 MCP 서버를 만들 수 있나요?

A: 네, TypeScript/JavaScript와 같은 다른 언어로도 MCP 서버를 구현할 수 있습니다. 자세한 내용은 MCP 문서를 참조하세요.

---

이 가이드를 통해 MCP 서버를 설정하여 Claude와 같은 AI 모델이 실시간 날씨 데이터에 접근할 수 있게 되었습니다. 더 많은 정보와 고급 기능은 공식 MCP 문서를 참조하세요.