Open-Meteo MCP Server

간단한 MCP(Model Context Protocol) 서버로, Claude와 같은 AI 어시스턴트가 무료 Open-Meteo API를 래핑하여 실제 날씨 데이터(현재 상태와 예보)를 조회할 수 있게 해줍니다. API 키가 필요 없습니다.

도구 정의, 로컬 실행, 실제 AI 클라이언트 연결까지 MCP 서버가 엔드 투 엔드로 작동하는 방식을 이해하기 위한 학습 프로젝트로 제작되었습니다.

기능

MCP 호환 클라이언트(예: Claude)에 연결되면 세 가지 도구가 노출됩니다:

그래서 사용자가 어시스턴트에게 "내일 리스본 날씨는 어때?"라고 물으면, 어시스턴트가 직접 이 도구들을 호출해 알아내고 답할 수 있습니다. 날씨 데이터가 사전에 프로그래밍되어 있는 것이 아니라 실시간으로 가져옵니다.

Related MCP server: Weather MCP Server

구성 방식

• src/server.ts — 세 가지 도구와 각 도구가 Open-Meteo API를 호출하는 방식을 정의합니다. 서버의 실제 "두뇌"에 해당하는 부분입니다.

• src/index.ts — 서버를 stdio(표준 입력/출력)로 실행합니다. 이 전송 방식은 MCP Inspector 같은 로컬 개발 도구와 서버를 하위 프로세스로 실행하는 데스크톱 앱에서 사용됩니다.

• src/http.ts — 동일한 서버를 Streamable HTTP로 실행하여 네트워크를 통해 접근할 수 있게 합니다(예: 어딘가에 호스팅하거나 브라우저 기반 클라이언트에서 접근). 이를 통해 로컬에 아무것도 설치하지 않고도 데모를 시연할 수 있습니다.

두 진입점 모두 server.ts의 동일한 도구 정의를 공유하므로 실제 로직이 존재하는 곳은 한곳뿐입니다.

실행하기

npm install
npm run build

로컬/stdio 모드(서버를 하위 프로세스로 실행하는 도구용):

npm start

HTTP 모드(원격 클라이언트 연결용, 예: 전달된 Codespaces 포트 또는 호스팅 제공업체를 통해):

node build/http.js

이 명령은 PORT로 설정 가능한 3000번 포트에서 일반 HTTP 서버를 시작하며, POST /mcp에 단일 MCP 엔드포인트와 GET /health 상태 확인 엔드포인트를 제공합니다.

클라이언트 없이 테스트하기

MCP Inspector의 CLI 모드는 브라우저 없이 터미널에서 직접 확인해 볼 수 있는 가장 빠른 방법입니다:

# See what tools are available
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# Actually call one
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name geocode_location --tool-arg name=London

AI 어시스턴트에 연결하기

• Claude Desktop / Claude Code: 클라이언트 설정에서 build/index.js를 stdio MCP 서버로 지정합니다.

• Claude.ai 맞춤 커넥터: 실행 중인 HTTP 인스턴스의 /mcp URL을 지정합니다(맞춤 커넥터를 허용하는 요금제 필요).

• Anthropic API 직접 사용: /v1/messages 요청의 mcp_servers 매개변수에 /mcp URL을 전달합니다. 이렇게 하면 사전 구축된 MCP 클라이언트 없이도 모든 맞춤 앱이나 페이지에서 도구를 사용할 수 있습니다.

확장을 위한 참고 사항

Open-Meteo에는 이 프로젝트에서 사용하는 것보다 훨씬 더 많은 변수와 엔드포인트가 있습니다(대기 질, 해양 예보, 과거/아카이브 데이터, 앙상블). 더 추가하려면 src/server.ts에 있는 기존 도구의 패턴을 따라, 자체 입력 스키마와 Open-Meteo 요청을 가진 새 server.tool(...) 블록을 등록하세요.

데이터 © Open-Meteo.com, CC BY 4.0.