基于MCP协议构建AI天气服务：从原理到Cursor集成实战

1. 项目概述一个为AI工作流注入气象能力的MCP服务最近在折腾AI Agent和自动化工作流发现一个挺有意思的需求如何让AI助手比如Cursor里的Claude或者你自己搭建的Agent能实时获取天气信息无论是规划出行、安排日程还是分析业务数据时加入气象维度天气数据都是一个高频且实用的信息源。今天就来拆解一个开源的解决方案——gifflet/weather-mcp。这本质上是一个遵循MCPModel Context Protocol协议构建的天气服务它能让你的AI开发环境特别是Cursor IDE直接拥有查询实时天气和预警的能力。简单来说这个项目就是一个“翻译官”和“接线员”。它把美国国家气象局NWS的官方API封装成一套标准化的工具并通过MCP协议暴露给像Claude这样的AI模型。当你在Cursor里用自然语言问“旧金山明天会下雨吗”背后的流程是Claude理解你的意图调用这个Weather MCP服务提供的“查询天气”工具服务去NWS拉取数据再把结构化的结果返回给Claude最后由Claude组织成一段流畅的回答告诉你。整个过程对开发者透明你只需要配置好就能像使用内置功能一样让AI调用外部天气数据。这个项目非常适合正在探索AI应用落地的开发者、希望增强个人或团队AI助手能力的效率爱好者以及对MCP协议感兴趣的工程师。它提供了一个非常清晰的范例展示了如何将一个常见的公共服务天气快速集成到现代AI开发栈中。接下来我会从设计思路、详细配置、深度使用到问题排查完整走一遍这个项目的实战过程并分享一些官方文档里没写的细节和坑点。2. 核心设计思路与MCP协议解析2.1 为什么选择MCP协议在深入代码之前必须先理解MCPModel Context Protocol。你可以把它想象成AI世界的“USB协议”或“驱动标准”。在MCP出现之前每个AI模型如Claude、GPT要想连接外部工具如数据库、API、计算器都需要定制化的集成工作量大且不通用。MCP的目标就是定义一套标准让任何符合该协议的工具称为MCP Server都能被任何支持该协议的AI客户端如Cursor、Claude Desktop即插即用。weather-mcp项目就是一个标准的MCP Server。它的核心价值不在于从零造轮子去爬取天气数据而在于标准化适配。它选择了美国国家气象局NWS这个权威、免费且无需API密钥的数据源然后按照MCP的规范将“获取地点天气”和“获取州预警”这两个功能包装成名为get_weather和get_alerts的“工具”Tools。AI客户端通过标准化的JSON-RPC over STDIO与这个Server通信调用这些工具。这种设计带来了几个关键优势解耦与复用性天气服务逻辑独立于任何特定的AI前端。今天你可以用在Cursor里问Claude明天换到另一个支持MCP的AI桌面应用这个Server无需任何修改就能继续工作。开发体验统一作为开发者你只需要按照MCP的规范定义工具、处理请求、返回结果来写这个Server。一旦完成它就自动获得了被众多AI客户端识别的能力。安全性MCP通信通常发生在本地或受信任的网络环境中避免了将敏感的AI对话上下文直接发送到不可控的第三方天气API数据流更可控。2.2 项目架构与数据流拆解理解了MCP的角色我们再看这个项目的具体架构。虽然项目README没有给出详细的架构图但我们可以从代码和配置中推断出其核心数据流[用户自然语言提问] ↓ [Cursor IDE / Claude 客户端] (MCP Client) ↓ (通过STDIO发送JSON-RPC请求) [weather-mcp Server] (MCP Server即本项目) ↓ (发起HTTP请求) [美国国家气象局(NWS) API] ↓ (返回JSON格式天气数据) [weather-mcp Server] ↓ (将数据格式化为MCP标准响应) [Cursor IDE / Claude 客户端] ↓ (组织成自然语言回答) [用户获得答案]这个链条中的核心就是我们这个weather-mcp服务。它内部主要做三件事工具注册在启动时向连接的客户端宣告“我这里有get_weather和get_alerts两个工具可用这是它们的调用格式。”请求路由监听来自客户端的JSON-RPC调用解析出用户想调用的工具名如get_weather和参数如location: “Sacramento”。数据代理与格式化将参数转换为对NWS API的特定HTTP请求获取原始数据后再清洗、提取关键信息如温度、天气状况、预警标题并包装成MCP规定的格式返回。这种“代理适配器”的模式非常经典也是构建MCP Server的通用思路。它把复杂、原始的API接口转换成了AI模型易于理解和使用的“功能按钮”。注意一个常见的误解是认为这个服务自己产生了天气数据。实际上它只是一个中间层数据完全来源于NWS。因此它的功能上限受限于NWS API最明显的限制就是仅支持美国境内的地理位置。这是由数据源决定的并非本项目设计缺陷。3. 从零开始的详细配置与实操要点官方Getting Started部分给出了基础步骤但在实际搭建中有几个细节容易卡住。下面我以macOS/Linux环境为例展开每一步的操作和背后的原理。3.1 环境准备与依赖深潜Node.js版本选择README要求v18或更高。这里有个关键点MCP协议本身对Node版本没有严格要求但v18是一个重要的LTS长期支持版本并且原生支持了fetchAPI一个用于发起网络请求的现代接口。这个项目在调用NWS API时很可能使用了fetch。如果你使用更老的版本如v16可能需要额外安装node-fetch这类polyfill库否则会报错。因此直接使用v18或更新的LTS版本如v20是最省事的选择。检查与安装Node.js打开终端运行以下命令node --version如果版本低于18建议使用nvmNode Version Manager来管理多版本。安装nvm后执行nvm install 18 nvm use 18Git与项目克隆这个无需多言确保系统已安装Git。克隆时注意网络如果GitHub访问慢可以考虑配置代理或使用镜像源。3.2 安装、构建与首次运行按照README的步骤git clone https://github.com/gifflet/weather-mcp.git cd weather-mcp npm install npm run build这三行命令分别完成了下载源代码、进入项目目录、安装依赖并构建。npm install会根据package.json文件下载所有必需的第三方库依赖。你可以打开package.json看看这个项目的依赖非常精简核心可能就是modelcontextprotocol/sdkMCP官方SDK和一些用于开发和构建的工具如TypeScript编译器、esbuild等。这体现了它作为一个轻量级适配器的定位。npm run build这个命令执行了项目的构建脚本。因为项目是用TypeScript写的源码在src/目录下build命令会将TypeScript代码编译成纯JavaScript代码并输出到build/目录。这样做的好处是生产环境运行的是优化后的、兼容性更好的JS文件而不是原始的TS文件。构建后验证构建完成后强烈建议手动测试一下生成的Server是否能够独立运行node build/index.js如果一切正常你会看到服务器启动的日志并可能提示它正在等待来自MCP客户端的连接通常是通过标准输入输出。此时你可以按CtrlC退出。这个步骤能提前发现一些环境或依赖问题比如某个模块找不到。3.3 MCP Server配置的绝对路径陷阱这是整个配置过程中最容易出错的一步。README里提到了在项目目录或家目录创建.cursor/mcp.json。我们详细拆解一下。理解“绝对路径”配置文件中的args参数指向的是/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js。这里的ABSOLUTE/PATH/TO/PARENT/FOLDER需要替换成你本地weather-mcp项目所在的父目录的绝对路径。举个例子假设你的项目克隆在/Users/yourname/Projects/weather-mcp。项目的父文件夹是/Users/yourname/Projectsbuild/index.js的路径是/Users/yourname/Projects/weather-mcp/build/index.js那么配置文件中的路径就应该是{ mcpServers: { weather-service: { command: node, args: [/Users/yourname/Projects/weather-mcp/build/index.js] } } }注意README示例中路径末尾是weather/build/index.js这是假设你的项目文件夹名就是weather。但根据克隆命令文件夹名默认是weather-mcp。所以你需要根据实际情况调整指向weather-mcp/build/index.js。如何获取绝对路径在终端中进入你的weather-mcp项目目录然后运行pwdPrint Working Directory命令这会打印出当前目录的绝对路径。你只需要在这个路径后面加上/build/index.js即可。项目级配置 vs 全局配置项目级配置在weather-mcp项目文件夹内创建.cursor/mcp.json。这种配置只在该项目被作为“项目”在Cursor中打开时生效。如果你在其他目录或新窗口工作这个服务不会出现。全局配置在用户家目录~或/Users/yourname创建.cursor/mcp.json。这种配置下无论你在Cursor中打开哪个项目天气服务都会作为可用的MCP服务器出现。对于这种通用工具服务我强烈推荐使用全局配置这样在任何项目中都可以方便地查询天气。配置文件命名与位置确保文件夹和文件名正确。是.cursor目录前面有点号是隐藏文件夹里面的文件是mcp.json。在macOS/Linux上你可以用以下命令快速创建# 在家目录创建全局配置 mkdir -p ~/.cursor echo { mcpServers: { weather-service: { command: node, args: [/ABSOLUTE/PATH/TO/weather-mcp/build/index.js] } } } ~/.cursor/mcp.json然后用文本编辑器如VSCode、Vim打开这个文件替换里面的路径为你实际的路径。4. 在Cursor IDE中的集成与深度使用配置完成后重启Cursor IDE是关键一步。因为Cursor会在启动时读取MCP配置。4.1 服务验证与连接重启后按照路径Cursor Settings Features MCP打开MCP设置页面。你应该能在服务器列表中看到weather-service并且其状态应该是“已连接”或类似的绿色标识。如果没看到点击页面右上角的刷新按钮。如果状态显示错误或无法连接请检查终端中直接运行node build/index.js是否报错。mcp.json中的路径是否正确尤其是绝对路径和文件名index.js是否拼写无误。是否有其他进程占用了可能的端口虽然MCP over STDIO一般不涉及网络端口但检查无害。4.2 自然语言查询的实战技巧连接成功后你就可以在Cursor的聊天窗口通常是和Claude对话中直接使用自然语言查询了。这背后的魔力在于Claude模型已经通过MCP协议知道了weather-service提供了哪些工具以及如何调用它们。有效的查询句式直接问询“What‘s the weather in Los Angeles today?” 洛杉矶今天天气如何包含状态“Is it going to rain in Seattle this weekend?” 西雅图本周末会下雨吗预警查询“Are there any flood warnings in Florida?” 佛罗里达州有洪水预警吗组合提问“What’s the weather and are there any alerts for New York?” 纽约的天气和预警情况如何理解AI的决策过程 当你发出查询时Claude会意图识别判断你的问题是否与天气相关。工具匹配在已知的MCP工具列表中寻找最匹配的工具。对于地点天气它会选择get_weather对于州级预警它会选择get_alerts。参数提取从你的自然语言中提取出必要的参数。例如从“What‘s the weather in Sacramento?”中提取location: “Sacramento”。执行与整合通过MCP客户端调用工具获得结构化的JSON数据然后将这些数据组织成一段通顺的人类语言回复给你。实操心得地名要具体尽量使用城市名如San Francisco而不是模糊的“湾区”。对于同名城市可以加上州缩写如Portland, OR或Portland, ME。预警查询以州为单位get_alerts工具的参数是state州缩写如CA、TX。所以问“Are there any alerts in Texas?”比“Are there any alerts in Houston?”更准确后者AI可能会先尝试用get_weather获取休斯顿天气但不会触发预警查询。时区问题NWS API返回的时间通常是UTC或本地时间。AI在回复时可能会进行转换但如果你对具体时间敏感可以在问题中明确例如“What‘s the weather in Chicago at 2 PM local time?”。4.3 超越简单查询探索高级集成可能性这个MCP服务的价值不止于手动聊天查询。你可以发挥创意将其集成到更自动化的流程中在代码注释或文档中触发在编写与天气相关的代码逻辑时你可以在注释里直接问“// 这里需要根据纽约的天气调整参数。当前纽约天气如何” Cursor的AI可以读取上下文并调用工具回答。任务规划与自动化脚本思路虽然不能直接通过这个服务写脚本但它给了你灵感。你可以设想一个自动化场景每天早晨一个本地脚本启动通过模拟MCP客户端调用这个天气服务获取你所在城市的天气和预警然后合成语音播报或发送到你的通知栏。理解工具调用原理打开Cursor的开发者工具如果支持或查看网络请求你有可能看到实际的JSON-RPC调用和响应。这对于调试或学习MCP协议细节非常有帮助。请求体大致会包含jsonrpc: “2.0”, method: “tools/call”, params: {name: “get_weather”, arguments: {location: “...”}}这样的结构。5. 常见问题排查与进阶调试指南即使按照步骤操作也可能会遇到问题。下面是我在实战中遇到的一些情况及其解决方法。5.1 服务连接失败症状Cursor的MCP设置页面中weather-service显示为断开、错误或根本不在列表中。排查步骤检查Server进程首先在终端中手动运行服务看是否有立即报错。cd /path/to/weather-mcp node build/index.js如果报错Error: Cannot find module ‘...’这通常是依赖未安装或构建未完成。回到项目根目录重新执行npm install npm run build。如果报错与fetch或网络相关检查你的网络连接因为服务需要访问api.weather.gov。NWS API在国内访问可能不稳定这是最大的潜在瓶颈。检查配置文件确认~/.cursor/mcp.json文件存在且格式正确JSON格式严格不能有尾随逗号。确认args中的路径是绝对路径并且指向的是构建后的build/index.js文件。一个快速验证的方法是在终端中直接用node命令运行这个绝对路径文件node “/Users/yourname/Projects/weather-mcp/build/index.js”如果这个命令能成功启动服务挂起等待连接说明路径和文件本身没问题。重启Cursor任何对mcp.json的修改都需要重启Cursor IDE才能生效。查看Cursor日志Cursor可能将MCP相关的错误日志输出到其控制台或特定的日志文件中。查找这些日志可以获得更具体的错误信息。5.2 查询无结果或返回错误症状AI回复“I couldn‘t get the weather”或返回一个API错误信息。排查步骤确认查询地点在美国境内这是最常见的原因。该服务只支持美国50个州及属地如关岛、波多黎各。尝试一个明确在美国的城市如”What‘s the weather in Omaha, NE?“。地点名称歧义有些地名可能对应多个州。尽量使用”城市名州缩写“的格式如”Springfield, IL“。NWS API限制NWS的公开API有速率限制。如果你短时间内进行大量查询可能会被暂时限制。错误信息中可能会包含”403 Forbidden“或提及速率限制。解决办法是稍等片刻再试。服务端日志如果你在手动运行node build/index.js的终端里看到服务启动那么在Cursor中查询时这个终端会打印出详细的请求和响应日志除非代码禁用了日志。观察这里是否有HTTP请求失败如4xx、5xx状态码的错误信息。5.3 性能优化与稳定性考量服务常驻与资源占用当你配置为全局MCP Server后Cursor启动时会尝试启动这个Node.js服务。这意味着会有一个常驻的Node进程。对于天气服务这种低频查询的工具资源占用通常可以忽略不计。但如果你发现Cursor启动变慢可以检查是否是多个MCP Server同时启动导致的。网络延迟所有天气数据都需要从api.weather.gov获取。如果你的网络到该服务延迟较高每次查询都会有一定等待时间通常1-3秒。这是由数据源决定的无法通过优化本项目代码解决。错误处理与重试目前的项目代码可能包含了基础的错误处理。但在实际使用中网络波动、API暂时不可用等情况时有发生。一个更健壮的实现可以考虑加入重试机制例如对网络错误重试1-2次和更友好的降级提示如“天气服务暂时不可用请稍后再试”。5.4 扩展思考如何支持中国天气很多国内开发者会问如何让它支持中国天气这需要对项目进行二次开发核心是更换数据源。寻找替代API你需要一个提供中国天气数据的API例如和风天气、心知天气等通常需要注册和API Key。修改工具实现在项目的源代码src/目录下很可能是tools/weather.ts和tools/alerts.ts这样的文件中找到get_weather和get_alerts这两个工具的函数实现。替换HTTP请求将函数内部向api.weather.gov发起的请求替换为向你选择的国内天气API发起的请求。适配数据格式国内API返回的JSON数据格式肯定与NWS不同。你需要解析新的响应格式提取出温度、天气状况、预警等信息并映射到原有工具返回的数据结构上。处理API密钥国内服务通常需要API Key。你需要设计一种安全的方式让用户配置例如通过环境变量读取并在代码中将其添加到请求头或参数中。重新构建修改完TypeScript源码后需要重新运行npm run build来生成新的build/index.js文件。这个过程实际上是将一个针对NWS的“适配器”改造成了针对另一个数据源的“适配器”是学习MCP Server开发的绝佳练习。