🌤️ Weather MCP Server (Node.js)

Node.js / Express 기반으로 구현된 원격 MCP(Model Context Protocol) 서버입니다. Streamable HTTP transport를 통해 get_weather 도구를 노출하여, Claude Code 등 MCP 클라이언트가 어떤 도시의 현재 날씨를 실시간으로 조회할 수 있습니다.

날씨 데이터는 wttr.in에서 제공됩니다 — 무료, 회원가입 불필요, API key 불필요.

✨ 기능 특징

• 🛰️ 원격 MCP 서비스: 공식 @modelcontextprotocol/sdk 기반으로 Streamable HTTP 전송을 구현하며, JSON 및 SSE 두 가지 응답 모드를 지원합니다.

• 🌆 전 세계 도시 지원: 도시 이름(예: Beijing, Tokyo, Paris)을 직접 전달하여 해당 지역의 날씨를 조회할 수 있습니다.

• 🔌 완전한 세션 관리: Mcp-Session-Id를 자동 생성/검증하며, 세션의 생성, 재사용, 종료(DELETE)를 지원합니다.

• 🧩 단일 파일로 즉시 사용: 데이터베이스 불필요, 설정 파일 0개, server.js 하나로 시작할 수 있습니다.

Related MCP server: MCP Weather Server — Demo

📦 환경 요구 사항

• Node.js ≥ 18(내장 fetch 포함, 추가 의존성 불필요)

🚀 빠른 시작

# 1. 安装依赖
npm install

# 2. 启动服务(默认端口 3000)
npm start

# 后台运行(日志写入 logs/server.log)
npm run start:bg

시작에 성공하면 서비스 주소는 다음과 같습니다:

http://localhost:3000/mcp

자주 사용하는 스크립트

🔌 MCP 클라이언트 구성

Claude Code 또는 Streamable HTTP를 지원하는 다른 MCP 클라이언트에서 서비스를 원격 MCP 서버로 등록합니다.

Claude Code

MCP 서버 목록을 통해 추가(/mcp → 추가 → HTTP):

{
  "type": "http",
  "url": "http://localhost:3000/mcp"
}

JSON 설정 파일 방식

{
  "mcpServers": {
    "weather": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🧰 제공되는 도구

get_weather

지정된 도시의 현재 날씨를 가져옵니다.

매개변수

반환 예시

当前 Beijing 的天气是晴(Sunny),温度 28°C(体感 30°C),湿度 45%,风速 12 km/h。

⚙️ 구현 설명

• 세션 격리: 각 세션은 독립적인 Server + transport 인스턴스를 보유하며(SDK의 connect()는 하나의 transport만 지원), Mcp-Session-Id 요청 헤더로 연결됩니다.

• 새 세션 흐름: Mcp-Session-Id가 없는 POST는 초기화 요청으로 간주되며, 서버가 세션 ID를 생성하여 Mcp-Session-Id 응답 헤더로 반환합니다(CORS의 exposedHeaders를 통해 브라우저 클라이언트에 명시적으로 노출).

• 호환성 처리: 세션 ID가 없는 GET SSE 프로브 요청은 404/400을 반환하는 대신 열린 SSE 스트림을 유지하여, Claude Code 등 클라이언트가 POST 초기화 흐름을 계속 진행할 수 있게 합니다.

• 안정적인 오류 반환: 날씨 API 호출 실패 시 전체 요청을 중단시키는 대신 isError: true 결과를 반환합니다.

🗂️ 프로젝트 구조

.
├── server.js          # 全部服务逻辑(单文件)
├── package.json       # 项目配置与脚本
├── logs/              # 运行时日志(已被 .gitignore 忽略)
└── LICENSE            # MIT 许可证

📄 License

MIT