Ambient Weather MCP

Ambient Weather MCP サーバー

AI アシスタントを Ambient Weather の個人用気象観測所データに接続する MCP（Model Context Protocol） サーバーです。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 で 2 種類のキーを生成します
   • 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

Docker イメージは、main へのプッシュごとに GitHub Container Registry にも公開されます。

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

CI/CD

main へのプッシュごとに、次の 2 つの GitHub Actions ワークフローが実行されます。

• ビルドとプッシュ — Docker イメージをビルドし、スモークテストを実行して、latest とコミット SHA のタグを付けて ghcr.io にプッシュします
• シークレットのスキャン — TruffleHog を実行して、誤ってコミットされたシークレットを検出します

pre-commit フック（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 キーごとに 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 の Claude Desktop では、Python を直接実行すると作業ディレクトリに関する問題が発生します。

「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 認可
• Claude Partner Network の事例紹介としての Medium 記事

クレジット

• Ambient Weather API
• Model Context Protocol
• FastMCP
• Yaw Nana Gyamfi Prempeh による開発
• Wilson Mar — メンタリング、観測所へのアクセス、MCP のリファレンス、weather-info

ライセンス

MIT