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 页面 获取你的 API Key。

2. 安装

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

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

# 或使用 uv
uv pip install -e .

3. 配置

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

config.env 结构：

# 必需
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 配置中添加：

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

或者直接使用系统 Python：

{
  "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 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（图片处理）

开发

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

# 运行测试
python -m pytest tests/

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

参考

• MiniMax Token Plan 文档
• OpenHanako Vision Bridge — 图片理解模块的架构参考
• MCP Protocol Specification

License

MIT