Ambee MCP Server 是 Ambee 官方的 Model Context Protocol（MCP）服务器，用于让任何兼容 MCP 的 AI 助手（如 Claude、ChatGPT、Cursor、VS Code、Ollama 等）直接访问实时的空气质量、花粉与天气数据。用户将助手指向该服务器后，助手即可通过直接调用 Ambee 数据来回答诸如“亚特兰大今天树花粉是否严重？”或“周六的户外活动是否应改为室内？”等问题，而不再依赖过时的训练数据猜测。
用途 将 Ambee 的实时环境数据接入 MCP 兼容的 AI 助手，使 AI 能基于真实数据回答有关空气质量、花粉和天气的问题。
主要能力 提供六种工具，覆盖三类数据集（空气质量、花粉、天气）的最新状况与 48 小时预报。每个工具接受以下定位参数之一：lat + lng（数字），或 place（自由文本，例如 "Bengaluru"）。同时发送两者或都不发送会在请求前被客户端拒绝。所有 /v3 端点原生支持 place，因此无需单独的地理编码步骤。可选参数包括：locale（布尔值）— 为每条记录添加 localTime 字段；aqiStandard（仅空气质量）— EPA（默认）、IN、UK、CN 或 CA；units（仅天气）— imperial（默认）、metric 或 si；speciesRisk（仅花粉）— 在区域支持时包含各物种风险等级。每个响应都会根据 Ambee 文档中的状态码进行检查。所有非 2xx 响应都会以 MCP 工具错误（isError: true）返回，并附带结合 Ambee 自身错误文本和简短后续操作提示的可读消息，以便调用助手解释失败原因，而不仅仅是展示原始状态码。
使用方式 需要 Ambee API Key，可在 Ambee API dashboard 免费获取。切勿提交密钥或将其放入纳入版本控制的配置文件中，详见 SECURITY.md。服务器通过 stdio 运行，启动后应在 stderr 看到 [ambee-mcp-server] running on stdio，进程会等待 MCP 消息。服务器使用标准 MCP over stdio，因此可与任何兼容客户端配合使用。命令和环境变量在各处相同，仅配置文件格式不同。
各客户端配置要点：
- Claude Desktop：添加到 claude_desktop_config.json。
- Cursor：添加到 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）。
- VS Code（GitHub Copilot / MCP 扩展）：添加到 .vscode/mcp.json。
- Windsurf：添加到 ~/.codeium/windsurf/mcp_config.json。
- Cline（VS Code 扩展）：在 Cline 的 MCP 设置面板添加新服务器，Args 为 /absolute/path/to/ambee-mcp-server/src/index.js，环境变量为 AMBEE_API_KEY=your-ambee-api-key；或直接编辑 cline_mcp_settings.json，使用与其他示例相同的 command / args / env 结构。
- Zed：添加到 Zed 的 settings.json 中的 context_servers 下。
- Ollama：Ollama 原生应用尚未直接支持 MCP，但任何 Ollama 模型都可以通过 MCP 感知的桥接或代理框架调用此服务器，因为 Ollama 暴露了 OpenAI 兼容 API，MCP 客户端库（如 mcp-use 或 LangChain 的 MCP 适配器）可通过其路由工具调用。文档给出了使用 mcp-use 与本地 Ollama 模型的最小示例。
- ChatGPT（开发者模式 / 自定义连接器）：ChatGPT 的 MCP 连接器支持（开发者模式、Team/Enterprise 工作区）期望远程 HTTP 服务器而非本地 stdio 进程。要以此方式暴露此服务器，需将其运行在 MCP 到 HTTP 的网关（如 mcp-remote 或小型反向代理）之后，并将生成的 URL 注册为 ChatGPT 设置中的自定义连接器。
- 任何其他 MCP 客户端：每个 MCP 客户端最终都需要相同的三件事——command、args 和 env 块；具体配置块放置位置请查阅客户端文档。
示例提示 “洛杉矶现在的空气质量有多糟？” “明天 PM2.5 什么时候最低，好让我外出跑步？” “我孩子对草过敏——周六早上在奥斯汀对她来说会很难受吗？” “90210 现在的紫外线指数是多少，用公制单位？” “比较我们班加罗尔和奥斯汀办公室的空气质量。”
适用场景 适合需要基于实时空气质量、花粉和天气数据回答问题的 AI 助手使用场景，例如户外活动规划、过敏风险查询、空气质量比较、紫外线指数查询等。
限制 所有工具均为只读；无法修改用户的 Ambee 账户或数据。MCP 调用与 REST 调用共享相同的 Ambee API 配额/速率限制。目前仅暴露 “latest” 与 “48-hour forecast”。Ambee 的 /v3 API 还支持历史数据和 120 小时预报——可查看开放 issue 或提交功能请求。
支持与贡献 问题/bug 请提交至 GitHub Issues；API 支持见 support.getambee.com；API 状态见 docs.ambeedata.com/api-status；安全报告见 SECURITY.md。欢迎贡献，详见 CONTRIBUTING.md。
