mirror-earth-mcp 0.3.0

镜像地球气象数据的官方 MCP Python 服务。

Mirror Earth MCP

mirror-earth-mcp 是镜像地球气象数据的 Python Model Context Protocol（MCP）服务，基于官方 MCP SDK 实现，提供天气查询、模型与要素目录、地名解析、本地 Markdown 参考资料和批量导出任务管理能力。

使用要求

• Python 3.10 或更高版本
• uv
• 使用需要认证的天气查询和批量导出工具时，需提供 Mirror Earth API Key。请前往镜像地球开放平台个人中心获取。

geocode 和 reverse_geocode 使用公开地名服务，不需要 API Key。

安装与启动

通过 uvx 直接运行 PyPI 中发布的包：

uvx --from mirror-earth-mcp mirror-earth-mcp

在 MCP 客户端的环境变量中设置 MIRROR_EARTH_API_KEY。API Key 可在镜像地球开放平台个人中心获取。服务使用 stdio 传输，只会向标准输出写入 JSON-RPC 响应。

MCP 配置

{
  "mcpServers": {
    "mirror-earth": {
      "command": "uvx",
      "args": ["--from", "mirror-earth-mcp", "mirror-earth-mcp"],
      "env": {
        "MIRROR_EARTH_API_KEY": "YOUR_MIRROR_EARTH_API_KEY"
      }
    }
  }
}

在 Codex CLI 中添加服务：

codex mcp add mirror-earth --env MIRROR_EARTH_API_KEY=YOUR_MIRROR_EARTH_API_KEY -- uvx --from mirror-earth-mcp mirror-earth-mcp

MCP 工具

工具	用途
list_models	列出实时预报、历史再分析和历史预报模型。
get_model_details	查询模型元数据、支持的要素与等压面。
list_variables	列出逐小时、逐日或逐月要素。
get_forecast	按经纬度查询天气预报。
get_historical_weather	查询 ERA5 历史天气数据。
get_archive_forecast	查询历史模型起报的预报数据。
get_seamless_weather	查询连续的 ERA5 与 ECMWF 天气数据。
geocode / reverse_geocode	解析地名与经纬度。
get_batch_usage	查询批量导出配额和使用情况。
estimate_batch_export / create_batch_export	预估并创建批量导出任务。
get_batch_task / list_batch_tasks / cancel_batch_task	管理批量导出任务。

服务还通过 mirror-earth://references/... MCP 资源公开内置的 API 和模型说明文档。

本地开发

uv sync
uv run pytest
uv build

构建产物输出到 dist/。发布新版本时，将 PyPI token 配置到 UV_PUBLISH_TOKEN 环境变量后执行：

uv publish