[MCP] MCP 서버 개발하기

by


이 포스트에서는 Model Context Protocol(MCP)을 활용하여 간단한 날씨 서버를 구축하고, 이를 Claude Desktop과 같은 클라이언트에 연결하는 방법을 단계별로 살펴보겠습니다.

무엇을 만들게 될까요?

대부분의 LLM은 실시간 날씨 데이터나 기상 경고를 가져오는 기능이 없습니다. 이 문제를 MCP로 해결할 수 있습니다. 우리는 다음 두 가지 도구를 노출하는 서버를 구축할 것입니다:

  • get-alerts: 특정 미국 주(State)의 날씨 경고 정보를 제공합니다.
  • get-forecast: 위도와 경도를 기반으로 상세한 날씨 예보를 제공합니다.

이 서버는 Claude Desktop뿐 아니라 다른 MCP 클라이언트와도 연동이 가능합니다.

MCP의 핵심 개념

MCP 서버는 다음 세 가지 주요 기능을 제공할 수 있습니다:

  • 리소스(Resources): API 응답이나 파일 내용과 같은 데이터를 클라이언트가 읽을 수 있도록 제공합니다.
  • 도구(Tools): LLM이 호출할 수 있는 함수이며, 사용자의 승인을 요구합니다.
  • 프롬프트(Prompts): 사용자에게 특정 작업을 도와주는 미리 작성된 템플릿입니다.

이번 튜토리얼은 주로 도구에 집중합니다.

사전 요구사항

  • Python 3.10 이상
  • MCP SDK (버전 1.2.0 이상)

환경 설정하기

아래 명령어로 환경 설정을 시작합니다:

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

다음으로, 프로젝트를 생성하고 종속성을 설치합니다:

uv init weather
cd weather
uv venv
.venv\Scripts\activate
uv add mcp[cli] httpx
new-item weather.py

서버 구축하기

패키지 임포트 및 서버 초기화

다음 코드를 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"

헬퍼 함수 정의

National Weather Service API 데이터를 가져오는 함수를 작성합니다:

async def make_nws_request(url: str) -> dict[str, Any] | None:
    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

도구(Tools) 구현

두 개의 도구를 정의합니다:

@mcp.tool()
async def get_alerts(state: str) -> str:
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

서버 실행하기

서버를 실행합니다:

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

실행 명령어:

uv run weather.py

Claude Desktop과 연동하기

Claude Desktop 설정 파일(claude_desktop_config.json)에 다음 내용을 추가합니다:

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

설정 파일 저장 후 Claude Desktop을 재시작하여 서버를 테스트합니다.

테스트하기

Claude Desktop의 MCP 도구 목록에서 날씨 도구를 확인하고, 다음 명령어로 테스트해 보세요:

  • “What’s the weather in Sacramento?”
  • “What are the active weather alerts in Texas?”

참고 자료

  • https://modelcontextprotocol.io/introduction


Leave a Comment