# MiniMax MCP Server

一个功能完整的 MiniMax Token Plan MCP Server，提供额度查询、网页搜索、图片理解和图片生成四种能力。基于 Python FastMCP 构建，可直接集成到 Claude Code 等支持 MCP 的客户端。

## 功能概览

| 工具 | 功能 | 使用的 MiniMax API |
|------|------|-------------------|
| `query_quota` | 查询 Token Plan 各模型剩余配额 | `/v1/token_plan/remains` |
| `web_search` | MiniMax 网络搜索 | `/v1/coding_plan/search` |
| `understand_image` | 图片理解（双模式 + 缓存） | `/v1/coding_plan/vlm` |
| `generate_image` | 图片生成（image-01 模型） | `/v1/image_generation` |
| `clear_vision_cache` | 清除视觉分析缓存 | - |

## 项目结构

```
minimax-mcp/
├── config.env.example       # 配置模板
├── pyproject.toml
├── src/minimax_mcp/
│   ├── server.py            # FastMCP 服务入口 + 5 个 Tool
│   ├── client.py            # MiniMax HTTP API 客户端
│   ├── config.py            # 配置管理（config.env → 环境变量 → 默认值）
│   ├── tools/
│   │   ├── quota.py         # 额度查询（5小时/日周期分类）
│   │   ├── web_search.py    # 网页搜索
│   │   ├── image_understand.py  # 图片理解（本地文件→Base64 转换）
│   │   └── image_generate.py    # 图片生成（自动保存本地）
│   └── vision/
│       ├── analyzer.py      # 分析器（双模式 + 缓存调度）
│       ├── prompts.py       # 结构化 Prompt 模板
│       └── cache.py         # LRU 内存缓存 + 磁盘 JSON 持久化
└── tests/
```

## 快速开始

### 1. 获取 API Key

在 [MiniMax 平台 Token Plan 页面](https://platform.minimaxi.com/subscribe/token-plan) 获取你的 API Key。

### 2. 安装

```bash
# 克隆仓库
git clone <repo-url>
cd minimax-mcp

# 安装依赖（需要 Python >= 3.10）
pip install -e .

# 或使用 uv
uv pip install -e .
```

### 3. 配置

```bash
cp config.env.example config.env
# 编辑 config.env，填入你的 API Key
```

`config.env` 结构：

```ini
# 必需
MINIMAX_API_KEY=你的_api_key

# 可选
MINIMAX_API_HOST=https://api.minimaxi.com          # 中国大陆
# MINIMAX_API_HOST=https://api.minimax.io          # 全球
MINIMAX_IMAGE_OUTPUT_DIR=~/Pictures/MiniMax         # 生成图片保存位置
MINIMAX_CACHE_DIR=~/.minimax-mcp/cache              # 视觉分析缓存位置
MINIMAX_VISION_DEFAULT_MODE=detailed                # quick 或 detailed
MINIMAX_CACHE_MAX_SIZE=256                          # 最大缓存条目
MINIMAX_CACHE_TTL_DAYS=7                            # 缓存过期天数
```

> **重要**：`config.env` 包含 API Key，已在 `.gitignore` 中排除。**切勿提交到 Git**。

### 4. 注册到 Claude Code

在 Claude Code 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "MiniMaxMCP": {
      "command": "uv",
      "args": ["run", "--directory", "<项目路径>/minimax-mcp", "minimax-mcp"]
    }
  }
}
```

或者直接使用系统 Python：

```json
{
  "mcpServers": {
    "MiniMaxMCP": {
      "command": "python",
      "args": ["-X", "utf8", "-m", "minimax_mcp.server"],
      "env": {
        "PYTHONPATH": "<项目路径>/minimax-mcp/src"
      }
    }
  }
}
```

## 工具详解

### 1. query_quota — 额度查询

查询 Token Plan 的模型配额使用情况，自动区分文本模型（5 小时周期）和其他模型（日周期）。

```
query_quota()

→ {
    text_models: [
      { model_name: "MiniMax-M3.5", used: 32, total: 100, remaining: 68, usage_pct: 32 }
    ],
    other_models: [
      { model_name: "image-01", used: 5, total: 50, remaining: 45, usage_pct: 10 }
    ],
    no_quota: [...],
    summary: "文本模型: 5:00:00 后重置 | 其他模型: 12:30:00 后重置"
  }
```

### 2. web_search — 网页搜索

通过 MiniMax 搜索引擎搜索网页内容。

```
web_search(query="OpenAI GPT-5 发布日期")

→ {
    success: true,
    results: [
      { title: "...", url: "...", snippet: "...", position: 1 },
      ...
    ],
    related_searches: [...],
    query: "OpenAI GPT-5 发布日期"
  }
```

### 3. understand_image — 图片理解

借鉴 [OpenHanako](https://github.com/anthropics/openhanako) Vision Bridge 的设计理念，提供两种分析模式。

**设计理念**：
- 将图片交给专门的视觉模型（MiniMax VLM）进行结构化分析
- 分析结果作为文本注入到 LLM 上下文中，使纯文本模型也能"理解"图片内容
- 内置 LRU 缓存（256 条目，磁盘持久化），相同图片+相同 prompt 不重复消耗配额

**双模式**：

| 模式 | 适用场景 | 输出格式 |
|------|---------|---------|
| `quick` | 快速了解图片内容 | ~300 词简洁描述 |
| `detailed`（默认） | 深度分析 | 7 维度结构化报告 |

**detailed 模式输出维度**：

| 维度 | 内容 |
|------|------|
| `image_overview` | 画面概览 |
| `visible_text` | 可见文字 |
| `objects_and_layout` | 物体与布局 |
| `charts_or_data` | 图表/数据 |
| `answer_to_request` | 针对用户问题的回答 |
| `evidence` | 分析依据 |
| `uncertainty` | 不确定性说明 |

```
understand_image(
    image_url="https://example.com/photo.jpg",   # 支持 HTTP URL 或本地路径
    prompt="图片里有什么错误提示？",                # 可选，特定问题
    mode="detailed",                              # quick 或 detailed
    use_cache=true                                # 默认启用缓存
)
```

> **注意**：MiniMax VLM 不支持坐标输出，因此暂未实现 OpenHanako 的 Visual Primitives 空间坐标标注能力。如需要坐标感知的图像分析，建议使用支持视觉原语的模型。

### 4. generate_image — 图片生成

使用 MiniMax image-01 模型生成图片。

```
generate_image(
    prompt="A serene lake at sunset with snow-capped mountains",
    model="image-01",           # 目前仅支持 image-01
    aspect_ratio="16:9",        # 1:1 / 16:9 / 9:16 / 3:4 / 4:3
    n=1,                        # 1-3 张
    prompt_optimizer=true,      # 启用提示词自动优化
    save_to_disk=true,          # 自动保存到本地
    response_format="base64"    # base64（可存本地）或 url（24h临时链接）
)
```

图片自动保存到 `MINIMAX_IMAGE_OUTPUT_DIR` 目录（默认 `~/Pictures/MiniMax`）。

## 架构设计

```
┌─────────────────┐     MCP Protocol     ┌──────────────────────┐
│  Claude Code /   │ ◄──────────────────► │  FastMCP Server       │
│  MCP Client      │     (stdio)          │  (server.py)          │
└─────────────────┘                       │                       │
                                          │  ┌─────────────────┐ │
                                          │  │ quota.py        │ │
                                          │  │ web_search.py   │ │
                                          │  │ image_*.py      │ │
                                          │  │ vision/analyzer │ │
                                          │  │ vision/cache    │ │
                                          │  └────────┬────────┘ │
                                          │           │           │
                                          │  ┌────────▼────────┐ │
                                          │  │ MiniMaxClient   │ │
                                          │  │ (HTTP/HTTPS)    │ │
                                          │  └────────┬────────┘ │
                                          └───────────┼───────────┘
                                                      │
                                          ┌───────────▼───────────┐
                                          │  MiniMax API          │
                                          │  api.minimaxi.com     │
                                          └───────────────────────┘
```

### 配置优先级

```
config.env 文件 → 环境变量 → 代码默认值
```

### 缓存机制（视觉分析）

- **内存缓存**：LRU 策略，最大 256 条目（可配置）
- **磁盘持久化**：JSON 格式，存储到 `MINIMAX_CACHE_DIR`
- **缓存 Key**：`SHA256(image_url + prompt + mode)`
- **TTL**：默认 7 天过期

## 依赖

- **Python** >= 3.10
- **mcp** >= 1.0.0（FastMCP / MCP Protocol）
- **httpx** >= 0.27.0（HTTP 客户端）
- **Pillow** >= 10.0.0（图片处理）

## 开发

```bash
# 克隆并安装开发依赖
git clone <repo-url>
cd minimax-mcp
pip install -e ".[dev]"

# 运行测试
python -m pytest tests/

# 直接启动 MCP 服务器
python -m minimax_mcp.server
```

## 参考

- [MiniMax Token Plan 文档](https://platform.minimaxi.com/document)
- [OpenHanako Vision Bridge](https://github.com/anthropics/openhanako) — 图片理解模块的架构参考
- [MCP Protocol Specification](https://modelcontextprotocol.io)

## License

MIT