Weather MCP Server

🚀 天氣MCP服務器

這是一個模型上下文協議（MCP）服務器，藉助WeatherAPI服務提供天氣信息。該服務器允許AI助手通過標準輸入輸出（stdio）通信獲取當前天氣、天氣預報，並搜索地點。

🚀 快速開始

本服務器可讓AI助手藉助標準輸入輸出通信獲取當前天氣、天氣預報並搜索地點。你可以按照以下步驟進行安裝和配置。

✨ 主要特性

• 當前天氣：獲取任意地點的即時天氣狀況
• 天氣預報：獲取長達14天的天氣預報
• 地點搜索：查找並驗證地點名稱
• 空氣質量數據：可選的空氣質量信息
• 調試日誌：全面的日誌記錄，便於故障排查
• 標準輸入輸出通信：通過標準輸入/輸出進行直接的MCP協議通信

📦 安裝指南

選項1：通過Smithery（推薦）

通過 Smithery MCP註冊表自動安裝：

npx -y @smithery/cli install weather-mcp-server --client claude

或者用於其他MCP客戶端：

npx -y @smithery/cli install weather-mcp-server

這將自動完成以下操作：

• 安裝天氣MCP服務器
• 將其添加到你的MCP客戶端配置中
• 提示你輸入WeatherAPI密鑰

選項2：手動安裝

1. 克隆或下載此倉庫
2. 獲取WeatherAPI密鑰：
   • 在 https://www.weatherapi.com 註冊
   • 從儀表盤獲取免費的API密鑰
   • ⚠️ 重要提示

   請確保你的API密鑰安全，切勿將其提交到版本控制系統。

3. 安裝依賴項：

uv sync

💻 使用示例

運行服務器

直接執行

WEATHER_API_KEY=your_api_key uv run server.py

啟用調試日誌

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

通過MCP客戶端

當你的MCP客戶端（如mcphost或Claude Desktop）連接到服務器時，服務器將自動啟動。

可用工具

1. weather_current

獲取某個地點的當前天氣狀況。 參數：

• q（必需）：地點查詢（城市名稱、座標、郵政編碼）
• aqi（可選）：是否包含空氣質量數據（“yes” 或 “no”，默認：“no”） 示例：

{
  "name": "weather_current",
  "arguments": {
    "q": "New York, NY",
    "aqi": "yes"
  }
}

2. weather_forecast

獲取1 - 14天的天氣預報。 參數：

• q（必需）：地點查詢
• days（可選）：預報天數（1 - 14，默認：1） 示例：

{
  "name": "weather_forecast",
  "arguments": {
    "q": "London, UK",
    "days": 7
  }
}

3. weather_search

搜索與查詢匹配的地點。 參數：

• q（必需）：搜索查詢 示例：

{
  "name": "weather_search",
  "arguments": {
    "q": "Paris"
  }
}

地點查詢格式

天氣工具支持多種地點格式：

• 城市名稱：“New York”、“London”
• 城市和州/國家：“New York, NY”、“London, UK”
• 座標：“40.7128,-74.0060”
• 郵政編碼：“10001”、“SW1A 1AA”
• 機場代碼：“JFK”、“LHR”

📚 詳細文檔

配置

環境變量

設置你的WeatherAPI密鑰：

export WEATHER_API_KEY=your_api_key_here

可選 - 啟用調試日誌：

export DEBUG=true

MCP客戶端配置

將此服務器添加到你的MCP客戶端配置（例如 config.json）中：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

啟用調試日誌，添加 DEBUG 環境變量：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here",
        "DEBUG": "true"
      }
    }
  }
}

測試

手動測試

使用JSON - RPC請求測試服務器：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

啟用調試日誌：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

工具測試

測試天氣工具：

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"weather_current","arguments":{"q":"New York"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

Docker支持

構建鏡像

docker build -t weather-mcp-server .

使用Docker運行

docker run --rm -i -e WEATHER_API_KEY=your_api_key weather-mcp-server

調試模式

服務器支持可選的調試日誌。設置 DEBUG 環境變量以啟用詳細日誌記錄。 日誌級別：

• INFO：基本服務器操作（默認）
• DEBUG：詳細的請求/響應信息、API調用（當 DEBUG=true 時）

錯誤處理

服務器能夠優雅地處理常見錯誤：

• 無效的API密鑰：返回帶有指導的錯誤消息
• 未找到地點：建議替代搜索詞
• 網絡問題：提供重試建議
• 速率限制：指示何時超出限制

依賴項

• httpx：用於API請求的HTTP客戶端
• asyncio：支持異步/等待
• 標準庫：json、logging、sys、os

API限制

WeatherAPI免費套餐包括：

• 每月100萬次調用
• 當前天氣和3天天氣預報
• 可升級以獲取更長的預報和更高的限制

故障排除

常見問題

1. “No content response received”
   • 檢查API密鑰是否正確設置
   • 驗證網絡連接
   • 查看調試日誌以查找錯誤
2. “API key not provided”
   • 設置 WEATHER_API_KEY 環境變量
   • 檢查MCP客戶端配置
3. “Location not found”
   • 嘗試不同的地點格式
   • 使用 weather_search 工具查找有效地點

調試輸出

通過設置 DEBUG 環境變量啟用詳細日誌記錄：

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py 2>&1 | grep -E "(DEBUG|ERROR)"

架構

此服務器使用以下方式實現MCP協議：

• 標準輸入輸出通信：通過標準輸入/輸出進行直接的JSON - RPC通信
• 異步事件循環：非阻塞請求處理
• 手動JSON - RPC：自定義實現以實現精確控制
• WeatherAPI集成：帶有錯誤處理的RESTful API調用

貢獻

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 徹底測試
5. 提交拉取請求

許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

支持

• WeatherAPI文檔：https://www.weatherapi.com/docs/
• MCP規範：https://spec.modelcontextprotocol.io/
• 問題反饋：在倉庫的問題跟蹤器中報告錯誤和功能請求

最後更新時間：2025年7月12日