MiniMax MCP Server
MiniMax MCP Server
一个功能完整的 MiniMax Token Plan MCP Server,提供额度查询、网页搜索、图片理解和图片生成四种能力。基于 Python FastMCP 构建,可直接集成到 Claude Code 等支持 MCP 的客户端。
功能概览
工具 | 功能 | 使用的 MiniMax API |
| 查询 Token Plan 各模型剩余配额 |
|
| MiniMax 网络搜索 |
|
| 图片理解(双模式 + 缓存) |
|
| 图片生成(image-01 模型) |
|
| 清除视觉分析缓存 | - |
Related MCP server: minimax-mcp
项目结构
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 Keyconfig.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 不重复消耗配额
双模式:
模式 | 适用场景 | 输出格式 |
| 快速了解图片内容 | ~300 词简洁描述 |
| 深度分析 | 7 维度结构化报告 |
detailed 模式输出维度:
维度 | 内容 |
| 画面概览 |
| 可见文字 |
| 物体与布局 |
| 图表/数据 |
| 针对用户问题的回答 |
| 分析依据 |
| 不确定性说明 |
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参考
License
MIT
Available Tools
5 toolsclear_vision_cacheA
清除图片理解缓存(手动触发)
将内存中的缓存数据强制写入磁盘,并返回当前缓存统计。
Inputs: no named parameters.
generate_imageA
使用 MiniMax image-01 生成图片,默认保存到本地
图片自动保存到配置的输出目录(默认 ~/Pictures/MiniMax)。
Args: prompt: 图片描述文本(英文效果最佳,中文也可) model: 模型名称,默认 image-01 aspect_ratio: 图片比例:1:1 / 16:9 / 9:16 / 3:4 / 4:3,默认 1:1 response_format: 默认 base64(自动存本地),改 url 则仅返回24h临时链接 n: 生成数量 1-3,默认 1 prompt_optimizer: 是否启用提示词优化,默认 true save_to_disk: 是否保存到本地(仅 base64 模式有效),默认 true
Inputs: prompt (required), model, aspect_ratio, response_format, +3 more.
query_quotaA
查询 MiniMax Token Plan 剩余额度
返回文本模型(5小时周期)和其他模型(日周期)的配额使用情况, 包括已用次数、剩余次数、使用百分比、重置时间等。
无需参数,使用 config.env 中配置的 API Key。
Inputs: no named parameters.
understand_imageA
分析图片内容 — 借鉴 OpenHanako Vision Bridge 设计
两种模式:
quick: 简洁描述(~300词),适合快速了解图片内容
detailed: 结构化 7 维度分析(image_overview / visible_text / objects_and_layout / charts_or_data / answer_to_request / evidence / uncertainty),参考 OpenHanako vision-bridge.js
支持缓存:同一图片+相同prompt不重复调用API(LRU + 磁盘持久化)
Args: image_url: 图片 URL(HTTP/HTTPS)或本地文件路径,支持 JPEG/PNG/GIF/WebP (≤20MB) prompt: 对图片的具体问题,如 "这张图片里有什么错误提示?" mode: "quick" 或 "detailed",默认 detailed use_cache: 是否使用缓存,默认 true
Inputs: image_url (required), prompt, mode, use_cache.
web_searchB
使用 MiniMax 进行网络搜索
Args: query: 搜索查询词,例如 "OpenAI GPT-5 发布日期"
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation (cache clearing, image generation, quota query, image analysis, web search) with no overlap in purpose.
All tool names follow a consistent verb_noun snake_case pattern (e.g., clear_vision_cache, generate_image, query_quota, understand_image, web_search).
Five tools is a well-scoped set for a server offering image generation, analysis, web search, cache management, and quota checking—each tool serves a clear and necessary function.
The tool set covers the core functionalities of the MiniMax AI service: image generation, image understanding, web search, cache management, and quota monitoring, with no obvious gaps.
Maintenance
Related MCP Connectors
Web search, scraping, RAG answers with citations, and translation as MCP tools.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceUnifies MiniMax's multimodal generation, web search, image understanding, audio, video, and music tools into a single MCP server for use with Claude and other clients.1MIT
- AlicenseNot gradedqualityDmaintenanceProvides web search, image understanding, text-to-speech, and image generation tools via the MiniMax API.MIT
- FlicenseNot gradedqualityCmaintenanceExposes Qwen AI Token Plan's harness tools (web search, web extraction, code interpreter, text-to-image, and image-to-image search) as MCP tools. It enables agents to perform real-time web searches, extract webpage content, execute code in a sandbox, and search images by text or image queries.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients such as Claude Desktop, Cursor, and Windsurf to perform web searches and analyze images through MiniMax APIs, returning structured search results and AI-generated answers about images from URLs or local files. It is tailored for coding-plan users working in code development workflows.-