날씨 조회 MCP 서비스 (Python 버전) 🌤

공식 mcp Python SDK(FastMCP) 기반으로 구현한 날씨 조회 MCP 서비스입니다. stdio를 통해 모든 MCP 클라이언트(예: Claude Desktop, WorkBuddy 등)와 통신하여, AI 어시스턴트가 지정된 도시의 현재 날씨를 실시간으로 조회할 수 있게 해줍니다.

💡 날씨 데이터는 Open-Meteo에서 제공되며, 회원가입 없이, API Key 없이 사용할 수 있습니다.

✨ 기능 특징

• ⚡ 순수 stdio 통신: 플러그 앤 플레이 방식으로, 포트를 개방하거나 HTTP 서비스를 실행할 필요가 없습니다.

• 🌍 다국어 도시명 지원: 北京, Beijing, Tokyo 등 중국어와 영어 도시명을 모두 지원합니다.

• 🔒 키(Key) 불필요: 데이터는 Open-Meteo에서 제공되며, 개인 데이터를 수집하지 않고 요청 본문도 전송하지 않습니다.

• 🛡 견고한 오류 처리: 도시가 존재하지 않거나 네트워크 오류가 발생해도 크래시 없이 친절한 한국어 안내를 반환합니다.

• 🎨 친숙한 반환 형식: 구조화된 텍스트 + 이모지로 구성되어 클라이언트에서 바로 표시하기 쉽습니다.

🛠 제공 도구

반환 예시

📍 北京（中国）当前天气
🌤  天气：晴
🌡  温度：27.3°C（体感 28.1°C）
💧 湿度：52%
🍃 风速：12.4 km/h
🕒 观测时间：2026-08-19T13:00

📋 환경 요구 사항

• Python >= 3.10(3.13 권장, 본인 기기에서 검증 완료)

• 외부 네트워크 접근 필요(Open-Meteo API 호출)

🚀 설치 및 실행

git clone https://github.com/<your-name>/weather-mcp-server-py.git
cd weather-mcp-server-py

# 创建虚拟环境（可选但推荐）
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行（stdio 模式，通常由 MCP 客户端拉起）
python weather_server.py

본 서비스는 표준 입출력(stdio)을 통해 클라이언트와 통신하며, python weather_server.py는 기본적으로 stdio 모드로 시작됩니다.

🔌 MCP 클라이언트에 연동하기

Claude Desktop / WorkBuddy의 claude_desktop_config.json / mcp.json을 예로 들어, 다음과 같은 구성을 추가합니다 (python3을 사용자 기기의 인터프리터 절대 경로로 바꾸고, Windows에서는 python.exe를 사용하세요):

{
  "mcpServers": {
    "weather": {
      "command": "python3",
      "args": ["/absolute/path/to/weather_server.py"]
    }
  }
}

저장 후 클라이언트를 재시작하면, 대화에서 "베이징 날씨 조회"를 요청할 수 있으며 모델이 자동으로 get_weather 도구를 호출합니다.

📁 프로젝트 구조

weather-mcp-server-py/
├── weather_server.py   # MCP 服务主实现（FastMCP）
├── requirements.txt    # 依赖清单
└── README.md           # 本说明

🧰 기술 포인트

• 도시 → 위경도: Open-Meteo 지오코딩 API 사용;

• 현재 날씨: Open-Meteo Forecast API 사용, current 필드로 온도 / 체감 / 습도 / 풍속 / 날씨 코드를 한 번에 획득;

• 날씨 코드 → 한국어 설명: 내장 WMO 날씨 코드 매핑 테이블 사용;

• 실행 중 네트워크를 사용할 수 없거나 도시를 찾을 수 없는 경우, 모두 친절한 한국어 오류 안내를 반환하여 도구가 항상 문자열을 반환하도록 보장합니다.

🤝 기여

더 많은 날씨 지표 추가, 더 많은 클라이언트 예시 지원, 테스트 추가 등 Issue와 Pull Request를 환영합니다.

📄 License

MIT © 2026 weather-mcp-server-py contributors