🌤️ 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)
• 🧩 单文件即用:无需数据库,零配置文件,一个 server.js 即可启动

📦 环境要求

• Node.js ≥ 18(内置 fetch,无需额外依赖)

🚀 快速开始

# 1. 安装依赖
npm install

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

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

启动成功后,服务地址为:

http://localhost:3000/mcp

常用脚本

命令	说明
npm start	前台启动服务
npm start:bg	后台启动,日志写入 logs/server.log
npm run dev	开发模式,文件变更自动重启
npm run status	查看 3000 端口服务是否在运行
npm run logs	实时查看日志
npm run stop	停止服务
npm run restart	重启服务
npm run restart:bg	后台重启

🔌 配置 MCP 客户端

在 Claude Code 或其他支持 Streamable HTTP 的 MCP 客户端中,将服务注册为远程 MCP 服务器。

Claude Code

通过 MCP 服务器列表添加(<kbd>/mcp</kbd> → 添加 → HTTP):

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

JSON 配置文件方式

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

🧰 提供的工具

get_weather

获取指定城市的当前天气情况。

参数

参数	类型	必填	说明
city	string	✅	城市名称,例如 Beijing、Tokyo

返回示例

当前 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 探测请求会保持一个打开的 SSE 流(而非返回 404/400),让 Claude Code 等客户端可以继续走 POST 初始化流程。
• 可靠的错误返回:天气 API 调用失败时返回 isError: true 的结果而非让整个请求崩溃。

🗂️ 项目结构

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

📄 License

MIT