AI导哈

天气数据API服务器

一个全面的天气数据模型上下文协议(MCP)服务器，提供实时天气、天气预报、天气警报、空气质量、天文学数据等功能，适用于需要精确天气信息的应用场景。

  • by OriShmila
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 orishmila/weather-api-mcp-server

使用说明

Weather API MCP服务器

一个用于天气数据的综合模型上下文协议（MCP）服务器，具有防弹模式验证功能。采用标准MCP框架构建，具有明确的工具模式、全面的测试和完整的输入/输出验证。

🌟 特性

天气工具

  • 当前天气状况 -实时天气，可选空气质量
  • 天气预报 -1-14天预报，包括警报和空气质量
  • 天气警报 -恶劣天气警告和公告
  • 空气质量信息 -污染水平和健康指数
  • 天文数据 -日出、日落、月相和日/月位置
  • 位置搜索 -通过名称、坐标、邮政编码或机场代码查找和识别位置
  • 时区信息 -任何位置的时区数据
  • 体育赛事 -体育赛事（足球、板球、高尔夫）的天气

高级功能

  • 🔍 全面的模式验证 -输入和输出的完整JSON模式验证
  • 📋 显式工具定义 -中定义的所有工具 tools.json 具有完整的模式
  • 🧪 广泛测试 -45+个测试用例，涵盖所有工具和边缘用例
  • ⚡ 高性能 -优化API调用成功率100%
  • 🛡️ 错误处理 -强大的验证和有意义的错误消息
  • 📊 实时验证 -API调用前验证的输入参数

📋 可用工具

工具 说明 必需参数 可选参数
get_current_weather 当前天气状况 query include_air_quality
get_weather_forecast 天气预报（1-14天） query days, include_air_quality, include_alerts
get_weather_alerts 天气预警和警报 query -
get_weather_airquality 空气质量测量 query -
get_astronomy_data 天文学和太阳/月球数据 query, date -
search_locations 搜索和查找位置（无天气数据） query -
get_timezone 时区信息 query -
get_weather_for_sport_event 体育赛事天气 query -

注： get_weather_history 可用，但需要高级WeatherAPI订阅。

🛠️ 需求

🚀 安装

手动安装

  1. 克隆存储库：

    git clone https://github.com/yourusername/weather-api-mcp-server.git
cd weather-api-mcp-server

  2. 使用uv安装依赖项：

    uv sync

  3. 设置API密钥：

    # Create .env file
echo "WEATHER_API_KEY=your_api_key_here" > .env

  4. 获取您的WeatherAPI密钥：

📖 用法

运行服务器

选项1（推荐）：通过uvx控制台脚本运行

添加到MCP客户端的设置中（例如Claude Desktop）：

{
  "mcpServers": {
    "weatherAPI": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/OriShmila/weather-api-mcp-server",
        "weather-api-mcp-server"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

选项2：本地运行（仓库签出）

# Start the MCP server from a local checkout
uv run python main.py

该服务器使用stdin/stdout通信协议作为MCP服务器运行。

测试服务器

# Run comprehensive test suite (45+ tests)
uv run python test_server.py

预期产量：

🌤️  Weather API MCP Server Test Suite
==================================================
✅ Loaded 9 tool schemas
✅ Mapped 9 tool functions
🔍 Validating schema structure...
✅ All schemas have valid structure
✅ All schemas have corresponding functions
✅ Loaded 5 schema definitions for $ref resolution

🧪 Running Tool Tests with Schema Validation
--------------------------------------------------
🚀 Running 45 test cases with full schema validation...

...

==================================================
🧪 TEST SUMMARY
==================================================
Total Tests: 45
✅ Passed: 45
❌ Failed: 0
📊 Success Rate: 100.0%

🔧 配置

环境变量

变量 描述 必填
WEATHER_API_KEY 您的WeatherAPI.com API密钥 是

工具架构

所有工具模式都在中定义 tools.json 与：

  • 输入验证 -参数类型、约束、模式
  • 输出验证 -响应结构和数据类型
  • $ref定义 -可重用的架构组件
  • 错误处理 -全面的验证规则

📊 架构验证

此服务器具有全面的JSON模式验证功能：

输入验证

  • ✅ 参数类型 （字符串、整数、布尔值）
  • ✅ 必填字段 验证
  • ✅ 模式匹配 （日期格式等）
  • ✅ 范围限制 （最小/最大值）
  • ✅ 枚举验证

输出验证

  • ✅ 响应结构 验证
  • ✅ 字段类型检查
  • ✅ 所需属性 验证
  • ✅ $ref决议 用于可重用定义
  • ✅ 嵌套对象验证

示例：日期验证

# ✅ Valid date format
"date": "2024-12-25"

# ❌ Invalid date format (caught by schema)
"date": "2024/12/25"  # Error: does not match '^\\d{4}-\\d{2}-\\d{2}$'

🧪 测试

服务器包括全面的测试：

  • 45个测试用例 涵盖所有工具
  • 每个工具5次测试 不同的场景
  • 错误案例验证 对于边缘情况
  • 真正的API调用测试 通过实时验证
  • 模式验证测试 用于输入/输出
  • 性能监控 响应时间

测试类别

  1. 阳性检测 -有效输入和预期输出
  2. 阴性测试 -无效输入和错误处理
  3. 边缘案例 -边界条件和限制
  4. 模式测试 -输入/输出验证
  5. 性能测试 -响应时间监控

🔗 MCP客户端集成

Claude桌面配置

添加到您的Claude Desktop MCP设置中：

{
  "mcpServers": {
    "weatherAPI": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/OriShmila/weather-api-mcp-server",
        "weather-api-mcp-server"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

其他MCP客户端

服务器实现标准MCP协议，并与任何兼容MCP的客户端一起工作：

  • stdin/stdout通信
  • JSON-RPC 2.0协议
  • 工具列表和执行
  • 全面的错误处理

📁 项目结构

weather-api-mcp-server/
├── main.py              # MCP server implementation
├── tools.json           # Tool schemas and definitions
├── test_server.py       # Comprehensive test suite
├── test_cases.json      # Test cases (45+ scenarios)
├── pyproject.toml       # Project dependencies
├── .env                 # Environment variables
└── README.md            # This file

🎯 查询示例

位置灵活性

# City names
"query": "London"
"query": "New York"

# Coordinates  
"query": "40.7128,-74.0060"

# Postal codes
"query": "10001"

# Airport codes
"query": "LAX"

天气预报

# Basic forecast
{
  "query": "Paris",
  "days": 3
}

# Advanced forecast with air quality and alerts
{
  "query": "Miami", 
  "days": 7,
  "include_air_quality": true,
  "include_alerts": true
}

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 添加新功能的测试
  4. 确保所有测试通过： uv run python test_server.py
  5. 提交拉取请求

🙏 致谢

相关 MCP