Openweather MCP

OpenWeatherMap MCP 服务器

一个使用Streamable HTTP传输的TypeScript MCP（模型上下文协议）服务器，通过OpenWeatherMap API提供天气预报数据。

概述

这款MCP服务器使AI助手和其他MCP客户端能够获取全球任何城市的天气预报。它采用最新的技术构建 @modelcontextprotocol/sdk 版本 1.20.1它为OpenWeatherMap的5天预报API提供了一个简单可靠的接口。

特点/功能

• ☀️晴天 天气预报获取任意城市的1-5天天气预报
• 🌍 世界（地球） 全球覆盖按城市名称搜索，可选国家代码
• 📊 表格/数据图表 详细数据温度（最低/最高/平均）、天气描述等
• 🔄 旋转（循环） MCP协议基于 @modelcontextprotocol/sdk v1.20.1 构建
• 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或直接保留为“🚀”以表示其形象。因此，这个表情可以翻译为“🚀（火箭）”或者直接使用“🚀”来传达其含义。 HTTP传输使用Streamable HTTP实现轻松部署
• 🛡️（盾形符号，常用于表示保护、防御等含义） 类型安全使用Zod验证的完整TypeScript实现

先决条件

• Node.js 22+（参见 .nvmrc （用于确切版本）
• OpenWeatherMap API密钥（免费层级可在 openweathermap.org（可译为“开放天气地图网站”））

安装

1. 克隆仓库：

git clone 
cd mcp-server-template-nodejs

1. 安装依赖项：

npm install

1. 创建环境文件：

cp .env.example .env

1. 将您的OpenWeatherMap API密钥添加到 .env:

OPENWEATHERMAP_API_KEY=your_api_key_here
MCP_HTTP_PORT=3000

用法

发展

启动开发服务器并启用热重载：

npm run dev

服务器将在 http://localhost:3000 当你对源代码进行更改时，它会自动重启。

生产构建（或发布构建）

为生产构建项目：

npm run build

编译后的JavaScript将输出到 dist/ 目录。

启动生产服务器

npm start

使用MCP Inspector进行测试

使用MCP检查器工具来测试您的服务器：

npm run inspector

可用工具

获取天气预报

获取指定城市的天气预报数据。

参数：

• city （字符串，必填）：要获取天气的城市名称
• country （字符串，可选）：两位国家代码（例如，'US'，'GB'）
• days （数字，可选）：预报的天数（1-5天，默认为3天）

示例：

{
  "city": "Paris",
  "country": "FR",
  "days": 5
}

回答： 返回一个格式化的天气预报，包含每日平均气温、最低/最高气温以及天气描述。

可用提示

天气预报提示

一个以友好、对话式的方式询问天气预报的提示模板。

API 端点

• POST /mcp - 主MCP通信端点
• GET /mcp - 返回“方法不允许”（405）
• DELETE /mcp - 返回“方法不允许”（405）

项目结构

src/
├── index.ts        # Express server with HTTP transport
├── server.ts       # McpServer with tools and prompts
├── config.ts       # Environment configuration with Zod validation
└── types.ts        # TypeScript types for OpenWeatherMap API

文件角色

src/index.ts

角色： HTTP服务器入口点

• 设置Express.js应用程序
• 为MCP协议配置可流式传输的HTTP传输
• 处理POST请求至 /mcp 终端（主要通信）
• 对于 GET 和 DELETE 请求返回 405（方法不允许）
• 管理服务器生命周期（启动、通过SIGINT信号关闭）
• 创建新的 McpServer 每个请求通过实例 getServer()

src/server.ts

角色： MCP服务器逻辑与工具定义

• 出口 getServer() 返回配置的函数 McpServer 例子
• 定义了 getWeatherForecast 使用Zod模式进行验证的工具
• 实现OpenWeatherMap API集成逻辑
• 处理API响应并格式化天气数据
• 定义了 weatherForecastPrompt 模板
• 包含天气数据处理的所有业务逻辑

src/config.ts

角色： 环境配置与验证

• 使用Zod模式验证所需的环境变量
• 确保 OPENWEATHERMAP_API_KEY 存在且非空
• 提供 MCP_HTTP_PORT 默认值为3000
• 如果配置无效，则以清晰的错误信息退出进程
• 出口类型 config 在整个应用程序中使用的对象

src/types.ts

角色： TypeScript 类型定义

• 定义 ForecastItem 单个天气数据点的接口
• 定义 ForecastResponse 完整API响应结构的接口
• 在处理OpenWeatherMap API响应时确保类型安全
• 记录API数据（温度、天气、风力等）的格式
• 被用于 server.ts 用于类型检查和自动完成

发展

添加新工具

要添加一个新工具，请修改 src/server.ts:

server.tool(
  "tool-name",
  "Tool description",
  {
    // Define your parameters using Zod schemas
    param: z.string().describe("Parameter description"),
  },
  async (args): Promise => {
    const { param } = args;
    // Your tool implementation
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param}`,
        },
      ],
    };
  },
);

添加新提示

要添加一个新的提示模板，请修改 src/server.ts:

server.prompt(
  "prompt-name",
  "Prompt description",
  async (): Promise => {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Your prompt content here`,
          },
        },
      ],
    };
  },
);

所使用的技术

• @modelcontextprotocol/sdk（注：此翻译保持原样，因为“@modelcontextprotocol/sdk”是一个特定的软件开发包或框架的名称，在中文中通常不直接翻译，而是保留其原样以表示特定的开发工具或库。） v1.20.1 - 最新MCP SDK，用于构建协议服务器
• Express.js v5.1.0 - 用于HTTP传输的Web框架
• 佐德 v3.23.8 - 模式验证
• TypeScript - 类型安全的开发
• OpenWeatherMap API - 天气数据来源

环境变量

资源

• 模型上下文协议文档
• MCP SDK 文档
• OpenWeatherMap API 文档
• Express.js 文档

许可证

这个项目是基于Alpic MCP服务器模板开发的。