Ambient Weather MCP

Ambient Weather MCP 服务

一个 MCP（Model Context Protocol） 服务，可将 AI 助手连接到 Ambient Weather 个人气象站数据。你可以用自然语言询问气象站信息，而不必解析 API 返回的原始 JSON。

功能

此服务将 Ambient Weather 气象站数据作为 MCP 工具提供。将其连接到 Claude Desktop、VS Code 或 Kiro，即可提出以下问题：

• “列出我的气象站”
• “我的气象站当前温度是多少？”
• “CC:7B:5C:51:EC:52 的天气状况如何？”

AI 会调用工具，服务从 Ambient Weather REST API 获取实时数据，然后由 AI 以自然语言呈现结果。

架构

┌──────────────────┐    stdio (JSON-RPC)    ┌────────────────────┐
│   MCP Client     │◄─────────────────────►│   MCP Server       │
│  Claude Desktop  │                        │   (this project)   │
│  VS Code / Kiro  │                        │                    │
└──────────────────┘                        │  src/server.py     │
                                            │    ↓ calls          │
                                            │  src/ambient_client │
                                            │    ↓ HTTPS          │
                                            └────────┬───────────┘
                                                     │
                                            ┌────────▼───────────┐
                                            │  Ambient Weather   │
                                            │  REST API          │
                                            │  rt.ambientweather │
                                            │  .net/v1           │
                                            └────────────────────┘

可用工具

工具	描述	参数
ping	健康检查——确认服务正在运行且密钥已配置	无
get_devices	列出账户中的所有气象站及最新读数	无
get_current_weather	获取指定气象站的完整天气报告	mac_address

先决条件

1. Ambient Weather API 密钥——在 https://dashboard.ambientweather.net/account 生成两个密钥
   • Application Key：标识 MCP 服务应用
   • API Key：授予设备数据的读取权限
2. 已安装 Python 3.13+
3. uv——现代 Python 包管理器。安装：curl -LsSf https://astral.sh/uv/install.sh | sh
4. 一台向 ambientweather.net 报告数据的 Ambient Weather 气象站（或拥有此类气象站的用户的 API 密钥）

设置（本地开发）

# Clone the repo
git clone https://github.com/NanaGyamfiPrempeh30/ambient-weather-mcp.git
cd ambient-weather-mcp

# Install dependencies (uv creates .venv automatically)
uv sync

# Configure API keys
cp .env.example .env
# Edit .env with your actual keys

# Test the server
uv run python -c "from src.server import ping; import asyncio; print(asyncio.run(ping()))"

你应该会看到：

Ambient Weather MCP server is running.
API Key: configured
Application Key: configured
API Client: ready

连接到 Claude Desktop

Windows（使用批处理文件）

1. 在项目根目录中创建 run_mcp.bat：

@echo off
cd /d C:\Users\YourUsername\ambient-weather-mcp
C:\Python313\python.exe -m src

2. 添加到 claude_desktop_config.json（位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ambient-weather": {
      "command": "cmd.exe",
      "args": ["/c", "C:\\Users\\YourUsername\\ambient-weather-mcp\\run_mcp.bat"],
      "env": {
        "AMBIENT_API_KEY": "your-api-key",
        "AMBIENT_APP_KEY": "your-application-key"
      }
    }
  }
}

macOS / Linux（直接配置）

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "ambient-weather": {
      "command": "uv",
      "args": ["run", "python", "-m", "src"],
      "cwd": "/path/to/ambient-weather-mcp",
      "env": {
        "AMBIENT_API_KEY": "your-api-key",
        "AMBIENT_APP_KEY": "your-application-key"
      }
    }
  }
}

3. 完全重启 Claude Desktop（从系统托盘退出，然后重新打开）。
4. 检查“设置”→“开发者”→“ambient-weather”是否显示为正在运行。
5. 在新聊天中提问：“使用 get_devices 工具列出我的气象站”

使用 Docker 运行

# Build
docker build -t ambient-weather-mcp .

# Run
docker run -i --rm \
  -e AMBIENT_API_KEY="your-api-key" \
  -e AMBIENT_APP_KEY="your-app-key" \
  ambient-weather-mcp

每次推送到 main 时，Docker 镜像也会发布到 GitHub Container Registry：

docker pull ghcr.io/nanagyamfiprempeh30/ambient-weather-mcp:latest

CI/CD

每次推送到 main 都会触发两个 GitHub Actions 工作流：

• 构建并推送——构建 Docker 镜像、运行冒烟测试，并将镜像推送到 ghcr.io，同时添加 latest 和提交 SHA 标签
• 密钥扫描——运行 TruffleHog，检测意外提交的密钥

每次提交前，预提交钩子（TruffleHog）也会在本地扫描。设置说明请参阅 .pre-commit-config.yaml。

项目结构

ambient-weather-mcp/
├── .github/
│   └── workflows/
│       ├── build-and-push.yml   # Docker build + push to ghcr.io
│       └── secret-scan.yml      # TruffleHog secret scanning
├── .kiro/
│   └── specs/
│       ├── requirements.md      # EARS-format requirements
│       ├── design.md            # Technical architecture
│       └── tasks.md             # Implementation tasks
├── kubernetes/
│   ├── namespace.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── servicemonitor.yaml
│   └── secret.yaml.example     # Secret template (safe to commit)
├── src/
│   ├── __init__.py              # Package marker
│   ├── __main__.py              # Entry point for python -m src
│   ├── server.py                # MCP server + tool definitions
│   └── ambient_client.py        # Ambient Weather REST API client
├── .env.example                 # API key template (safe to commit)
├── .gitignore                   # Excludes .env, .venv, __pycache__
├── .dockerignore                # Excludes secrets from Docker image
├── .pre-commit-config.yaml      # TruffleHog pre-commit hook
├── Dockerfile                   # Container build recipe (uses uv)
├── pyproject.toml               # Python dependencies (managed by uv)
├── uv.lock                      # Locked dependency versions
├── run_mcp.bat                  # Windows launcher for Claude Desktop
├── DEBUG_LOG.md                 # Error tracking log
└── README.md                    # This file

API 速率限制

Ambient Weather API 限制：

• 每个 API 密钥每秒 1 个请求
• 每个 Application Key 每秒 3 个请求

服务包含一个 60 秒 TTL 缓存，可自动遵守这些限制。气象站每 5 分钟才报告一次数据，因此缓存不会造成任何损失。

环境变量

变量	必需	描述
AMBIENT_API_KEY	是	Ambient Weather API 密钥
AMBIENT_APP_KEY	是	Ambient Weather Application 密钥
CACHE_TTL_SECONDS	否	缓存时长，单位为秒（默认：60）
LOG_LEVEL	否	DEBUG、INFO、WARNING、ERROR（默认：INFO）

故障排除

“No module named src” — 请确保从项目根目录运行。在 Windows 上使用 Claude Desktop 时，请采用上文所示的 cmd.exe + 批处理文件方法。

Claude Desktop 中出现“Server disconnected” — 在 Windows 上，请采用 cmd.exe + 批处理文件方法。在 Windows 上，直接执行 Python 会导致 Claude Desktop 出现工作目录问题。

“401 Unauthorized” — API 密钥无效。请前往 https://dashboard.ambientweather.net/account 重新生成密钥。

“No weather stations found” — API 密钥未关联任何气象站。你需要有一台已注册到账户的实体 Ambient Weather 气象站。

“429 Too Many Requests” — 已触发速率限制。请等待几秒钟。如果问题持续出现，请增大 CACHE_TTL_SECONDS。

如需查看已遇到问题及其解决方法的完整记录，请参阅 DEBUG_LOG.md。

后续计划

• CI/CD 流水线（GitHub Actions → ghcr.io）
• 用于 ArgoCD 部署的 Kubernetes 清单
• Kiro 规范驱动工作流（需求、设计、任务）
• TruffleHog 密钥扫描（pre-commit + GitHub Actions）
• 从 pip 迁移到 uv
• 用于查询历史数据的 get_weather_history 工具
• 安全扫描工具（ruff、bandit、semgrep、safety）
• 用妥善的密钥管理方案替换 .env
• 用于基于网络部署的 HTTP 传输
• 发布到 MCP 市场（mcp.so、Smithery、Sevalla）
• 用于安全多用户访问的 MCP OAuth 授权
• 撰写 Medium 文章，作为 Claude Partner Network 案例研究

致谢

• Ambient Weather API
• Model Context Protocol
• FastMCP
• 由 Yaw Nana Gyamfi Prempeh 构建
• Wilson Mar — 指导、气象站访问权限、MCP 参考资料、weather-info

许可证

MIT