MCP协议实战：用QWeather Server让AI应用实时获取天气数据

你有没有遇到过这样的场景：让AI助手报一下今天的天气，它要么含糊其辞，要么直接告诉你“我无法获取实时数据”。这不怪模型，大模型的训练数据是有截止日期的，而天气是每时每刻都在变化的信息。QWeather MCP Server正好解决了这个痛点——它是和风天气官方推出的MCP服务，把天气数据能力封装成AI可以调用的标准化工具，让Claude、Codex、Cursor这类支持MCP的AI应用能实时查询天气。这篇文章我从协议原理讲到部署实战，再讲到问题排查，全程用我实际跑通的步骤说话，无论你是AI应用开发者、智能体爱好者，还是第一次接触MCP的新手，都能照着做出来。

我最初接触MCP是在调试几个工具类服务，那会儿最大的感受就是：配置本身不难，难的是你不知道为什么连不上、为什么工具没注册上。所以这篇文章我会把踩过的坑一并整理出来，帮你少走弯路。

1. QWeather MCP Server到底解决了什么问题

1.1 大模型没有“现在”，MCP补上实时数据缺口

大语言模型的本质是“通过训练数据学习到的概率分布来生成文本”，训练数据截止日期决定了它不知道训练之后发生的事。你问“今天上海天气怎么样”，模型如果训练数据里没有今天的天气，它就只能靠编造，或者给出一个“某年某月某日”的过时回答。这不是模型笨，而是信息边界问题。

要解决实时信息获取，业界尝试过几种方案：让模型自己访问网页，效果不稳定，页面结构和反爬策略随时会变；用RAG把网页内容向量化后检索，链路长、维护成本高；给模型接API，每个API都要单独写适配层。MCP最大的价值在于把“接入外部数据/工具”这件事标准化了。AI应用只要支持MCP协议，就能接上任何符合协议的MCP Server，不管是查天气、查数据库、操作浏览器还是控制MATLAB，协议是同一套。

1.2 为什么天气场景特别适合用MCP来打通

天气数据有三个特点：变化快、地域性强、结构相对统一。变化快意味着不能靠训练数据，训练数据里的“昨天”对今天没有意义；地域性强意味着用户必须给出具体地点，模型需要理解“朝阳区”“长安区”到底指哪里；结构统一则意味着API返回的JSON字段相对规范，适合直接交给模型整理成自然语言回答。

QWeather MCP Server能返回的数据维度很全：温度、体感温度、湿度、风速风向、气压、能见度、紫外线指数、空气质量、未来几天的预报，部分地区还有分钟级降水预报和天气预警。这些数据如果靠人肉去查再贴给AI，效率太低；如果靠模型幻觉去猜，又会出错。有了MCP Server，AI应用在对话中直接调用工具拿数据，回答自然就“眼见为实”了。

2. MCP协议的核心原理与QWeather的实现拆解

2.1 Host、Client、Server，三者各司其职

MCP（Model Context Protocol）是一个开放协议，规范了AI应用（Host）与外部工具/数据源（Server）之间的通信。整个体系里，Host是“大脑”，比如Claude Desktop、Codex CLI这类承载模型交互的客户端；Server是“外设”，比如QWeather MCP Server负责把天气能力暴露出来；而MCP Client是Host内部负责和Server通信的模块，它负责握手、发现工具、发起调用。

打个比方：MCP有点像USB-C接口。Host是电脑，Server是各种外设。以前你可能需要给每个外设配一根专属线，每个API都要写一套定制适配；现在只要外设都遵循MCP这个“接口标准”,插上就能用。QWeather MCP Server负责把和风天气的API“翻译”成MCP能理解的能力描述，Host侧的语言模型则负责理解用户意图、决定何时调用工具、把工具返回的JSON整理成自然语言回答。

2.2 三大原语：Tools、Resources、Prompts

MCP协议定义了三种核心能力，QWeather Server主要用到的是Tools（工具）。Tools是“可执行的动作”，Server把每个动作声明成带名称、描述和参数Schema的JSON定义，Host侧模型看到这些定义，就能在合适的时候发起调用。比如一个叫get_weather_now的工具，描述是“查询指定地点的当前天气”，参数是location（城市名或经纬度），模型看到用户问天气，就知道该调用它。

Resources（资源）是“可读取的数据”，适合暴露结构化文档或文件内容。Prompts（提示词）是可复用的提示词模板，可以在特定场景下引导模型用特定方式回答。QWeather MCP Server最核心的部分在Tools。通过tools/list方法，Host可以拿到Server能提供的所有工具列表；通过tools/call方法，Host可以按参数调用具体工具。整个通信基于JSON-RPC 2.0，每次请求都清晰地标明方法名和参数，出问题的时候排查起来比较直观。

2.3 stdio与HTTP/SSE：两种传输方式的取舍

QWeather MCP Server支持两种主流传输方式。stdio模式是本地子进程通信，你的MCP客户端直接启动一个本地进程，通过标准输入输出和它通信。这种模式配置简单、无需网络，适合个人电脑上做验证和开发，启动后信息直接打在终端里，排错效率高。HTTP/SSE模式则是把Server跑成一个远程服务，客户端通过网络请求访问，适合多台设备共享、或者放入服务器环境由多个AI应用调用。

我实际用下来的建议是：本地开发首选stdio，日志清晰，任何异常能第一时间看到；如果需要部署到服务器给多端使用，再用Docker起一个HTTP模式的实例，通过SSE端点对外提供服务。两条路我都跑通过，后面的部署部分会分别说明。

2.4 天气查询的数据链路：从地名到自然语言

一条完整的数据链路是这样的：用户说“北京现在多少度”，模型在Host侧分析出需要调用天气工具，把“北京”作为location参数传给Server；Server收到请求后，先去和风天气的地理编码接口把“北京”解析成对应的LocationID（或者直接使用调用方传入的经纬度），再调用实况天气接口拿到JSON数据；返回给模型后，模型把“温度25.1°C，湿度42%，东北风3级”这类数据整理成用户熟悉的自然语言回答。

这里有个关键细节：地名到地点ID的解析至关重要。地球上叫“长安”的地方不止一个，如果直接拿中文名去查天气，很容易查到错误地点的数据；同样，“滨江”“新城”这类名称在多个城市都有对应地点。更稳妥的做法是让用户传经纬度，或者先在对话中通过地理编码接口确认LocationID后再进入天气查询。这也是为什么你在配置QWeather Server时，我建议在系统提示词中引导模型优先使用结构化的地点参数，而不是裸地名——模型本身并不知道全球有几万个同名地点，把歧义消除的工作交给地理编码服务，比让模型猜靠谱得多。

3. 从零部署QWeather MCP Server

3.1 准备工作：注册开发者账号并获取API Key

部署的第一步是去和风天气控制台注册开发者账号，创建一个项目。注意项目类型要选对：如果你做的是AI应用集成，通常选Web API类型，拿到的是API Key；另外还有Android、iOS SDK类型的密钥，那不能用于服务端。创建项目后，把API Key复制出来，这就是你的认证凭证。

有一点容易踩坑：免费版项目的调用额度有限，而且不同套餐对QPS的限制不一样。你在部署MCP Server之前，建议先到控制台看一眼配额，确认免费版能否满足你的使用场景。如果只是个人学习和原型验证，通常够用；如果要做生产级应用，可能需要升级套餐。API Key属于敏感信息，不要硬编码在代码里，更不要提交到Git仓库，万一泄露被拿去刷量，吃亏的是自己。

3.2 部署方式一：用npx本地启动（最快）

如果你的电脑上已经有Node.js环境（建议Node 18以上），最快的方式是用npx直接启动。在终端执行：

bash复制npx @qweather/mcp-server --api-key YOUR_API_KEY

如果本地没有预先安装npm包，npx会临时下载并执行；如果你希望固定版本，可以用npm install -g全局安装后再执行。启动后，Server会在stdio模式下等待MCP Client的消息，看起来像“卡住”了，这是正常的，它不是在报错，而是在等待host端发起握手。这个阶段出现的任何输出，都会成为后续排查问题的重要线索。

3.3 部署方式二：Docker运行HTTP服务

如果你打算把QWeather MCP Server跑在服务器上，让多个客户端远程访问，推荐用Docker。启动命令类似：

bash复制docker run -d --name qweather-mcp \
  -e QWETHER_API_KEY=your-api-key \
  -p 8000:8000 \
  qweather/mcp-server

容器启动后，服务会监听8000端口，通过HTTP/SSE对外提供MCP能力。在MCP客户端配置远程Server时，需要填写两个URL：一个用于SSE连接，另一个用于消息发布。具体路径以你实际部署时命令行输出的信息为准。Docker方式的优势是环境隔离、启动快、容易迁移，缺点是日志不像本地运行那么直观，所以容器起来后一定要先用docker logs -f确认启动日志里没有报错，再往下接客户端。

3.4 接入Claude Desktop、Codex、Cursor

把QWeather MCP Server接进客户端，本质就是在客户端的配置文件中声明一个MCP Server条目。以Claude Desktop为例，macOS路径是~/Library/Application Support/Claude/claude_desktop_config.json，Windows是%APPDATA%\Claude\claude_desktop_config.json，添加如下配置：

json复制{
  "mcpServers": {
    "qweather": {
      "command": "npx",
      "args": ["@qweather/mcp-server"],
      "env": {
        "QWETHER_API_KEY": "your-api-key"
      }
    }
  }
}

保存后重启Claude Desktop，在对话中问“北京现在天气怎么样”，看到模型调用了天气工具，就说明接入成功。Codex的配置在~/.codex/config.toml，格式类似：

toml复制[mcp_servers.qweather]
command = "npx"
args = ["@qweather/mcp-server"]
env = { QWETHER_API_KEY = "your-api-key" }

改完配置后重启Codex CLI，在会话里检查工具列表，确认qweather服务是否在线。Cursor则在设置页面的MCP配置入口添加同样的条目即可。每个客户端的配置入口不同，但核心都是那几条字段：command、args、env，理解了这个，换什么客户端都不慌。

3.5 先用MCP Inspector做最小验证

不要急着把MCP Server接进业务系统，先用官方调试工具MCP Inspector做一次最小验证。启动命令是：

bash复制npx @modelcontextprotocol/inspector

启动后会打开一个本地调试页面，在工具配置里填入你的Server启动命令和参数，就能看到tools/list返回的工具列表，还能手动测试某个工具的调用。这个工具的好处是把你和具体客户端解耦，如果这里能调通，说明Server本身没问题，之后接任何客户端都只是配置问题。如果这里都调不通，那就安心排查Server启动和API Key的问题，不用怀疑是Claude还是Codex的锅。

4. 工具选型、参数配置与生产级注意事项

4.1 常用查询参数和返回字段

QWeather MCP Server的常用参数不多，但每个都可能影响结果。location参数支持城市名、LocationID和经纬度三种形式；lang参数控制返回语言，默认中文就够用；unit参数控制单位制，公制用m，英制用i。实际返回的数据维度很多，温度、体感、湿度、风向风速、气压、能见度、云量、紫外线等一应俱全。

如果你需要预报数据，工具列表里一般会有未来3天、7天甚至15天的预报工具，还有空气质量、天气预警等独立工具。用的时候注意：不同的工具对免费版的配额消耗不一样，频繁调用会被限流。我实测的感觉是，轮询式地每几分钟拉一次全量预报完全是浪费配额，生产环境建议做缓存，比如同一地点5分钟内不重复请求，把结果缓存在内存或Redis里，能大幅降低调用压力。

4.2 MCP与Agent Skill、Function Calling有什么区别

很多初次接触MCP的人会把这三个概念搞混。Function Calling是模型厂商在模型API层提供的“函数调用”机制，模型根据用户输入输出一个符合JSON Schema的调用参数，应用侧拿到参数再自己执行逻辑，它绑定在特定的模型供应商上。MCP则是更底层的通用协议，把“接入外部工具”标准化，和具体模型供应商解耦。

Agent Skill是另一个概念，更偏向“把完成某项任务所需的多步流程、上下文、工具调用序列封装成一个可复用的技能”。你可以这样理解：MCP解决的是“能连什么”，Skill解决的是“该怎么做”；两者不是替代关系，Skill的内部实现完全可以通过调用MCP工具来完成。实际项目里，你可以用多个MCP Server提供能力底座，再用Skill把常见的天气问答流程固化下来，各司其职。如果只盯着某一个概念，容易把自己的架构设计做窄，还是按场景搭配用最合理。

4.3 API Key安全、配额管理和团队协作

在生产环境里配置QWeather MCP Server，有几个我踩过坑后总结的要点。第一，API Key不要写死在配置文件的明文里，建议通过环境变量注入；如果你用Docker，用--env-file或者容器的密钥管理机制。第二，团队多人共用同一个Server时，建议在服务器端部署HTTP模式，所有成员只连同一个端点，Key只存在于服务器上，不散落到每个人的本地配置里。第三，做好限流和降级，天气查询这种高频操作如果失败，Server侧的返回最好能提示“稍后重试”，避免模型拿着错误数据一本正经地胡说八道。

另外提醒一句：你在控制台创建的API Key有类型区分，Web API Key和Android/iOS SDK的Key不能混用。把SDK Key填进MCP Server里，调用时会直接返回认证失败，这也是新手最常犯的错误。我见过不少人在群里问“为什么我的Server起不来”，最后发现就是Key类型选错了，换一个Web API Key立刻解决。

5. 常见问题与排查技巧实录

5.1 401认证失败

如果你启动QWeather MCP Server时一切正常，但调用工具时返回401或者认证错误，先检查API Key本身：是不是复制多了空格或换行符；是不是把SDK Key当成Web API Key用了；是不是免费版项目已经过期或超额。另外，有些老项目用的是JWT签名方式认证，新项目用的是API Key明文方式，这两种认证方式在请求头里的字段不同，如果Server版本和API Key格式不匹配，也会报401。

这类问题排查起来最快的方法是直接拿curl请求一次和风天气的HTTP API，如果curl能返回数据而MCP不行，问题大概率出在MCP Server的Key配置上。如果curl都返回401，说明Key本身有问题，回控制台重新生成一个再试。

5.2 客户端工具注册不上

这是MCP新手最常遇到的问题：配置写了，但在客户端里看不到任何工具。逐个排查下来，最常见的原因是JSON配置文件语法错误，比如多了一个逗号、双引号写错成单引号；其次是npx路径问题，Windows用户如果没把Node.js的安装目录加入PATH，npx命令找不到，进程起不来；再有就是网络问题，npx首次下载包时如果下载超时，Server自然无法启动。

我的建议是分三步走：在终端里先手动执行一遍配置里的command，确认Server能正常启动；接着用MCP Inspector连一次，确认工具列表能出来；最后才回到客户端配置里检查JSON或TOML格式。这“三步定位法”基本能覆盖绝大多数“注册不上”的问题。如果你在Windows上的PowerShell里直接运行配置命令报错，可以在JSON里把command改成"cmd"、args改成["/c", "npx", "@qweather/mcp-server"]。

5.3 查询结果和实际情况不符

结果不准通常不是Server的问题，而是地点解析的问题。前面说过，中文地名存在大量重名，直接传“长安”这类地名，地理编码接口可能返回的不是你预期的那个“长安”。解决办法是在传参时用LocationID或经纬度，比如北京的location建议直接写对应的LocationID或116.41,39.92。

另外，免费版对海外部分城市的覆盖可能有限，如果你查国外城市返回空数据，先确认和风天气的API是否覆盖该地区，不要误以为是MCP配置问题。还有一种常见情况是缓存：有些客户端会对工具返回值做短期缓存，你明明改了地点，返回的却是上次的结果。遇到这种，先等一下再查，或者干脆换一个没查过的地点测试，就能快速判断是不是缓存在捣鬼。

5.4 连接超时和进程中断

HTTP模式下如果远程Server连接超时，先确认服务器端口是否对外开放、防火墙是否放行；SSE连接还有一个特性，如果长时间没有消息交互，连接可能被服务端或中间网络设备断开，客户端遇到断开会自动重连，但如果你在Server侧做了自定义网络配置，要确认心跳机制是正常的。

本地stdio模式下，如果Server进程启动后异常退出，多半是Node版本太低或者依赖没有装全，把报错日志贴给AI辅助分析往往很快能找到原因。强烈推荐你遇到诡异问题就先看日志，别在配置里反复猜。日志里通常会明确告诉你哪一步失败了，是查找不到工具，还是API请求被拒，信息量大得多。

5.5 避坑清单速查

多跑几个MCP Server之后，我对MCP的态度从“又一个新概念”变成了“基础设施”。它的优势不是单个工具多强大，而是把AI应用和外部世界的连接方式标准化了。QWeather MCP Server只是一个开始，你可以用同样的思路接进去数据库、浏览器、设计工具，甚至自己写一个MCP Server把内部系统开放给AI。最后再分享一个小经验：先通过MCP Inspector把Server侧验证通透，再接到具体的AI客户端里，这个顺序能帮你省掉大量“为什么工具没注册上”的排查时间。另外，API Key这类敏感信息，记得用环境变量管理，别为了图省事直接写死在配置里——这件事我在协作项目里吃过亏，希望大家不要再踩。