weather-mcp

OpenWeatherMap 기반의 날씨 도구를 제공하는 TypeScript MCP 서버입니다.

도구

전송 방식

공식 MCP 문서: https://modelcontextprotocol.io/docs/

라이브 원격 서버 (Render)

Render 무료 티어에 배포되어 있습니다:

Cursor 설정 (원격)

Settings → MCP 또는 ~/.cursor/mcp.json에 다음을 추가하세요:

{
  "mcpServers": {
    "weather": {
      "url": "https://weather-mcp-ts.onrender.com/mcp"
    }
  }
}

Cursor에서 로컬 빌드나 API 키가 필요 없습니다 — 키는 Render의 환경 변수에 있습니다.

Render 무료 티어 참고: 서비스는 약 15분 동안 비활성 상태면 종료됩니다. 다음 요청은 콜드 스타트로, MCP가 응답하기까지 최대 약 50초가 걸릴 수 있습니다. Cursor 도구가 깨어나는 중인 것처럼 보이면 /health를 한 번 호출하세요.

Related MCP server: mcp-weatherapi

사전 요구 사항 (로컬 전용)

• Node.js 20+

• pnpm (또는 npm/yarn)

• OpenWeatherMap API 키 (여기서 발급)

설정 (로컬)

pnpm install
cp .env.example .env

.env를 편집하고 키를 설정하세요:

OPEN_WEATHER_MAP_API_KEY=your_key_here
TRANSPORT=stdio

서버를 빌드하세요:

pnpm run build

이 명령은 실행 가능한 진입점을 dist/index.js에 작성합니다.

Cursor에 추가 (로컬 stdio)

Cursor는 기본적으로 프로젝트 루트에서 이 프로세스를 시작할 때 환경 변수를 로드하지 않으므로, Node의 --env-file 플래그를 사용해 절대 경로로 환경 파일을 전달하세요.

1. Cursor Settings → MCP를 열거나 ~/.cursor/mcp.json을 편집하세요.

2. mcpServers 아래에 weather 항목을 추가하세요:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "--env-file",
        "/ABSOLUTE/PATH/TO/weather-mcp/.env",
        "/ABSOLUTE/PATH/TO/weather-mcp/dist/index.js"
      ]
    }
  }
}

/ABSOLUTE/PATH/TO/weather-mcp를 실제 프로젝트 경로로 바꾸세요 (예: 저장소 루트에서 pwd 실행). .env에서 TRANSPORT=stdio를 유지하세요 (또는 설정하지 않음).

대안: 환경 변수 인라인

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPEN_WEATHER_MAP_API_KEY": "your_key_here",
        "TRANSPORT": "stdio"
      }
    }
  }
}

키가 mcp.json에 남지 않도록 .env + --env-file을 선호합니다.

1. 저장한 후 Settings → MCP에서 서버를 껐다 켜세요 (또는 Cursor를 재시작).

2. 서버가 연결됨으로 표시되고 get_current_weather와 get_forecast가 나열되는지 확인하세요.

코드 변경 후

pnpm run build

그런 다음 Cursor에서 MCP 서버를 다시 로드하세요.

Streamable HTTP (로컬)

HTTP 모드는 POST/GET /mcp(구성 가능)와 GET /health에서 MCP를 제공합니다. Streamable HTTP는 공식 SDK의 createMcpHandler + toNodeHandler로 구성됩니다.

pnpm run build
TRANSPORT=http PORT=3000 pnpm run start
# or
pnpm run start:http

다음과 같은 출력이 보일 것입니다:

Weather MCP Server running on http://0.0.0.0:3000/mcp (Streamable HTTP)

Render에 배포

1. 이 저장소(프로젝트 루트)에서 Web Service를 생성하세요.

2. 빌드: pnpm install && pnpm run build (또는 npm 동일 명령).

3. 시작: node dist/index.js (또는 pnpm run start).

4. 환경 변수:

   • TRANSPORT=http

   • OPEN_WEATHER_MAP_API_KEY=...

   • PORT는 Render가 자동으로 설정합니다.

5. MCP URL: https://<your-service>.onrender.com/mcp
   이 배포: https://weather-mcp-ts.onrender.com/mcp

HTTP 엔드포인트는 인증이 없습니다. URL을 아는 사람은 누구나 도구를 호출할 수 있습니다. 널리 공유하기 전에 인증을 추가하세요.

수동 스모크 테스트 (OpenWeatherMap)

.env가 설정된 상태에서:

node --env-file=.env -e "
import { getApiKey, buildCurrentWeatherUrl, makeOWMRequest, formatCurrentWeather } from './dist/utils.js';
const apiKey = getApiKey();
const data = await makeOWMRequest(buildCurrentWeatherUrl({ apiKey, city: 'Yaounde,CM', units: 'metric' }));
console.log(data ? formatCurrentWeather(data, 'metric') : 'failed');
"

원격 헬스 체크:

curl -s https://weather-mcp-ts.onrender.com/health

저장소 구조

weather-mcp/
├── README.md
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    ├── index.ts      # stdio + Streamable HTTP entry
    ├── server.ts     # tool registration
    ├── types.ts
    └── utils.ts

참고 사항

• .env를 커밋하지 마세요 (gitignore에 포함됨).

• Stdio 서버는 MCP JSON-RPC 외에는 stdout에 출력하면 안 됩니다. 로그는 stderr(console.error)로 보내세요.

• 무료 OpenWeatherMap 플랜은 현재 날씨와 여기서 사용하는 5일 / 3시간 예보를 지원합니다.

라이선스

ISC