Ambient Weather MCP

环境天气MCP服务器

一 MCP（模型上下文协议） 将AI助手连接到的服务器 环境天气 个人气象站数据。询问有关气象站的自然语言问题，而不是从API解析原始JSON。

它的作用

此服务器将您的环境气象站数据作为MCP工具公开。将其连接到Claude Desktop、VS Code或Kiro，您可以问以下问题：

• “列出我的气象站”
• “我车站现在的温度是多少？”
• “CC:7B:5C:51:EC:52的条件是什么？”

人工智能调用该工具，服务器从环境天气REST API获取实时数据，人工智能以自然语言呈现结果。

建筑

┌──────────────────┐    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           │
                                            └────────────────────┘

可用工具

先决条件

1. 环境天气API键 --生成两者https://dashboard.ambientweather.net/account

- 程序键：标识MCP服务器应用程序 - API密钥：授予对设备数据的读取权限

1. Python 3.13+ 安装
2. 紫外线 --现代Python包管理器。安装： curl -LsSf https://astral.sh/uv/install.sh | sh
3. 环境气象站 向ambientweather.net报告（或访问某人拥有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

连接到克劳德桌面

Windows（带批处理文件）

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

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

1. 添加 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桌面配置：

{
  "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"
      }
    }
  }
}

1. 完全重新启动Claude Desktop（从系统托盘退出，重新打开）。
2. 检查设置→ 开发者→ 环境天气节目 跑步.
3. 在新的聊天中，问：“使用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

Docker镜像也会在每次向main推送时发布到GitHub容器注册表中：

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

CI/CD

每一次推动 main 触发两个GitHub操作工作流：

• 构建和推送 --构建Docker镜像，运行冒烟测试，并使用以下命令推送到ghcr.io latest 并提交SHA标签
• 秘密扫描 --运行TruffleLog以检测意外泄露的秘密

预提交钩子（TruffleLog）也会在每次提交之前进行本地扫描。看 .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费率限制

API环境天气强制执行：

• 每个API密钥每秒1个请求
• 每个应用程序密钥每秒3个请求

服务器包括一个60秒的TTL缓存，以自动保持在这些限制范围内。气象站每5分钟才报告一次，所以缓存不会丢失任何东西。

环境变量

故障排除

“没有名为src的模块” --确保从项目根目录运行。在带有Claude Desktop的Windows上，使用 cmd.exe +如上所示的批处理文件方法。

Claude Desktop中的“服务器已断开连接” --在Windows上，使用 cmd.exe +批处理文件方法。直接执行Python在Windows上与Claude Desktop存在工作目录问题。

“401未经授权” -API密钥无效。在以下时间重新生成https://dashboard.ambientweather.net/account

“未找到气象站” -API密钥没有附加任何工作站。您需要在帐户中注册一个物理环境气象站。

429请求太多 --达到速率限制。等几秒钟。增加 CACHE_TTL_SECONDS 如果它继续发生。

看 DEBUG_LOG.md 了解所遇到问题及其解决方案的完整历史。

接下来是什么

• \[x\] CI/CD管道（GitHub操作→ ghcr.io）
• \[x\] ArgoCD部署的Kubernetes清单
• \[x\] Kiro规范驱动的工作流程（需求、设计、任务）
• \[x\] TruffleLog秘密扫描（预提交+GitHub操作）
• \[x\] 从pip迁移到uv
• \[ \] get_weather_history 历史数据查询工具
• \[\]安全扫描工具（流氓、土匪、semgrep、安全）
• \[\]用适当的机密管理替换.env
• \[\]用于基于网络的部署的HTTP传输
• \[\]发布到MCP市场（MCP.so、Smithery、Sevalla）
• \[\]用于安全多用户访问的MCP OAuth授权
• \[\]作为Claude Partner Network案例研究的中篇文章

学分

• API环境天气
• 模型上下文协议
• FastMCP
• 由...建造 Yaw Nana Gyamfi Prempeh

许可证

麻省理工学院