Metadata-Version: 2.5
Name: mirror-earth-mcp
Version: 0.6.0
Summary: 镜像地球气象数据的官方 MCP Python 服务。
Project-URL: Homepage, https://gitee.com/gfyml/mirror-earth-mcp
Project-URL: Repository, https://gitee.com/gfyml/mirror-earth-mcp.git
Author: Mirror Earth
License: MIT
Keywords: mcp,mirror-earth,weather
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<3,>=2
Description-Content-Type: text/markdown

# Mirror Earth MCP

`mirror-earth-mcp` 是镜像地球气象数据的 Model Context Protocol（MCP）服务，提供天气查询、模型与要素目录、地名解析、批量导出任务管理及开发者版试用会员领取能力。

## 快速选择

| 模式 | 推荐场景 | 用户需要安装 | 更新方式 |
| --- | --- | --- | --- |
| **在线 MCP（推荐）** | 日常使用、团队接入、希望始终使用最新版 | 不需要 | 平台统一更新，无需用户操作 |
| **本地 MCP** | 离线网络环境、二次开发、需要自托管或调试 | Python 和 uv | 用户自行更新包与配置 |

无论使用哪种模式，都需要自己的镜像地球 API Key。可在[镜像地球开放平台个人中心](https://open.mirror-earth.com/account/profile)获取。

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

## 模式一：在线 MCP（推荐）

在线 MCP 使用正式服务地址 `https://api.mirror-earth.com/mcp`。无需安装 Python、uv 或 MCP 包；服务会持续更新，用户无需手动升级。

在支持远程 HTTP MCP 的客户端中新增以下配置：

```json
{
  "mcpServers": {
    "mirror-earth": {
      "type": "http",
      "url": "https://api.mirror-earth.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_MIRROR_EARTH_API_KEY"
      }
    }
  }
}
```

将 `YOUR_MIRROR_EARTH_API_KEY` 替换为自己的 Key。服务端会透传请求头中的 Key，因此每位用户的配额、会员等级和试用领取状态独立。

配置文件模板见 [mcp-config.remote.example.json](mcp-config.remote.example.json)。

## 模式二：本地 MCP

本地模式使用 stdio 协议，适用于需要本地调试、自行托管或希望控制运行版本的使用者。

### 前置条件

- Python 3.10 或更高版本
- [uv](https://docs.astral.sh/uv/)

### 通用配置

推荐通过 `uvx` 直接运行已发布的包：

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

如果不使用 `uvx`，先安装包后改用 Python 启动：

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

对应的 MCP 配置：

```json
{
  "mcpServers": {
    "mirror-earth": {
      "command": "python",
      "args": ["-m", "mirror_earth_mcp.server"],
      "env": {
        "MIRROR_EARTH_API_KEY": "YOUR_MIRROR_EARTH_API_KEY"
      }
    }
  }
}
```

本地模式发布新版本后，需要自行升级或重启运行环境；希望免安装、免维护时，请使用在线 MCP。

## 客户端配置提示

**在线 MCP：** 在客户端的远程 HTTP MCP 设置中填写地址 `https://api.mirror-earth.com/mcp`，并添加 `X-API-Key` 请求头。

**本地 MCP：** 在客户端的本地 stdio MCP 设置中填写 `uvx mirror-earth-mcp`，并设置 `MIRROR_EARTH_API_KEY` 环境变量。

常见位置：

- Claude Desktop：`claude_desktop_config.json` 顶层的 `mcpServers`
- Cursor：项目 `.cursor/mcp.json` 或 MCP 设置
- Windsurf：`~/.codeium/windsurf/mcp_config.json` 或 MCP 设置
- Cline、Roo Code 等：MCP Servers 设置

## MCP 工具

| 工具 | 用途 |
| --- | --- |
| `list_models` | 列出实时预报、历史再分析和历史预报模型。 |
| `get_model_details` | 查询模型元数据、支持的要素与等压面。 |
| `list_variables` | 列出逐小时、逐日或逐月要素。 |
| `get_api_document` | 读取内置 API 参考文档（批量导出参数、查询参数、接口说明等）。 |
| `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` | 管理批量导出任务。 |
| `claim_trial_membership` | 领取 3 天开发者版会员体验（每用户仅一次）。 |
| `get_trial_status` | 查询是否已领取过开发者版会员体验。 |

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

## 部署与开发

- 服务端 Docker 部署、HTTPS、反向代理及运维说明见 [部署指南](docs/deployment.md)。
- 本地开发：

```powershell
uv sync
uv run pytest
uv build
```

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

```powershell
uv publish
```
