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/

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

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

# 或使用 uv
uv pip install -e .

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

# 必需
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                            # 缓存过期天数

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

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

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 后重置"
  }

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

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

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

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临时链接）
)

┌─────────────────┐     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 文件 → 环境变量 → 代码默认值

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

# 运行测试
python -m pytest tests/

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