mirror-earth-mcp 0.3.4

镜像地球气象数据的官方 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。

安装与启动

这个服务使用 MCP 官方的 stdio transport，不依赖 Codex 专用协议或插件。只要客户端支持配置本地 MCP server，就可以接入。

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

uvx mirror-earth-mcp

如果客户端所在环境没有 uv，也可以先安装 Python 包，再使用 Python 启动：

python -m pip install mirror-earth-mcp
python -m mirror_earth_mcp.server

在 MCP 客户端的 server 配置中设置 MIRROR_EARTH_API_KEY。API Key 可在镜像地球开放平台个人中心获取。geocode 和 reverse_geocode 不需要 API Key。

通用 MCP 配置

下面是 MCP 客户端普遍使用的 server 定义。将 YOUR_MIRROR_EARTH_API_KEY 替换成真实 Key；如果只使用地名解析工具，也可以删除 env 字段。

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

command、args 和 env 是启动本地 stdio MCP server 的关键字段：

• command: 启动器，例如 uvx、python 或 Python 的绝对路径。
• args: 传给启动器的参数。使用 uvx 时为 ["mirror-earth-mcp"]；使用 Python 时为 ["-m", "mirror_earth_mcp.server"]。
• env: 传给 MCP server 的环境变量。

Claude Desktop

将上面的 mirror-earth 对象放入 Claude Desktop 的 claude_desktop_config.json：

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

文件顶层保留 mcpServers，不要把完整示例再嵌套一层。修改后重启 Claude Desktop。

Cursor

可以在项目根目录创建 .cursor/mcp.json，或者在 Cursor 的 MCP 设置中添加同一个 server。文件格式仍然是：

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

Windsurf

将同一个 JSON 配置放入 Windsurf 的 MCP 配置文件，通常为：

~/.codeium/windsurf/mcp_config.json

也可以通过 Windsurf 的 MCP 设置界面添加。保存后重启或重新加载 MCP 服务。

Cline / Roo Code 及其它 Agent

在客户端的 MCP servers 设置中新增一个本地 server，填写：

名称: mirror-earth
类型: stdio
命令: uvx
参数: mirror-earth-mcp
环境变量: MIRROR_EARTH_API_KEY=YOUR_MIRROR_EARTH_API_KEY

如果客户端要求 JSON，直接使用上面的通用配置。不同 agent 的配置文件路径和 UI 名称可能不同，但服务端定义不变；不要使用只属于 Codex 插件的 .codex-plugin/plugin.json 作为其它客户端的配置文件。

如果不能使用 uvx，改为：

{
  "command": "python",
  "args": ["-m", "mirror_earth_mcp.server"],
  "env": {
    "MIRROR_EARTH_API_KEY": "YOUR_MIRROR_EARTH_API_KEY"
  }
}

其中 python 必须是已经安装 mirror-earth-mcp 的 Python 环境；在 Windows 上也可以将 command 改为该 Python 解释器的绝对路径。

Codex CLI

Codex CLI 可以使用快捷命令添加服务：

codex mcp add mirror-earth --env MIRROR_EARTH_API_KEY=YOUR_MIRROR_EARTH_API_KEY -- uvx 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