Skip to main content
Glama
deenesjakoruzh
longhz

MiniMax MCP Server

by longhz
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MiniMax MCP Server

A fully functional MiniMax Token Plan MCP Server, providing four capabilities: quota query, web search, image understanding, and image generation. Built on Python FastMCP, it can be directly integrated into MCP-supported clients like Claude Code.

Feature Overview

Tool

Function

MiniMax API Used

query_quota

Query remaining quota for Token Plan models

/v1/token_plan/remains

web_search

MiniMax web search

/v1/coding_plan/search

understand_image

Image understanding (dual mode + cache)

/v1/coding_plan/vlm

generate_image

Image generation (image-01 model)

/v1/image_generation

clear_vision_cache

Clear vision analysis cache

-

Related MCP server: Kimi Coding MCP

Project Structure

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/

Quick Start

1. Get API Key

Obtain your API Key from the MiniMax Platform Token Plan page.

2. Installation

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

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

# 或使用 uv
uv pip install -e .

3. Configuration

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

config.env structure:

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

Important: config.env contains the API Key and is excluded in .gitignore. Do not commit to Git.

4. Register to Claude Code

Add to your Claude Code MCP configuration:

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

Or use the system Python directly:

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

Tool Details

1. query_quota — Quota Query

Query the model quota usage of the Token Plan, automatically distinguishing between text models (5-hour cycle) and other models (daily cycle).

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 — Web Search

Search for web content via the MiniMax search engine.

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

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

3. understand_image — Image Understanding

Drawing on the design philosophy of OpenHanako Vision Bridge, it provides two analysis modes.

Design Philosophy:

  • Offload images to a specialized vision model (MiniMax VLM) for structured analysis

  • Inject analysis results as text into the LLM context, allowing pure text models to "understand" image content

  • Built-in LRU cache (256 entries, disk-persistent); identical image + identical prompt does not consume extra quota

Dual Modes:

Mode

Use Case

Output Format

quick

Quickly understand image content

~300-word concise description

detailed (default)

In-depth analysis

7-dimension structured report

detailed mode output dimensions:

Dimension

Content

image_overview

Image overview

visible_text

Visible text

objects_and_layout

Objects and layout

charts_or_data

Charts/data

answer_to_request

Answer to user question

evidence

Analysis evidence

uncertainty

Uncertainty notes

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

Note: MiniMax VLM does not support coordinate output, so OpenHanako's Visual Primitives spatial coordinate annotation capability is not yet implemented. If coordinate-aware image analysis is required, it is recommended to use a model that supports visual primitives.

4. generate_image — Image Generation

Generate images using the MiniMax image-01 model.

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

Images are automatically saved to the MINIMAX_IMAGE_OUTPUT_DIR directory (default ~/Pictures/MiniMax).

Architecture Design

┌─────────────────┐     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     │
                                          └───────────────────────┘

Configuration Priority

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

Caching Mechanism (Vision Analysis)

  • Memory Cache: LRU strategy, max 256 entries (configurable)

  • Disk Persistence: JSON format, stored in MINIMAX_CACHE_DIR

  • Cache Key: SHA256(image_url + prompt + mode)

  • TTL: 7-day expiration by default

Dependencies

  • Python >= 3.10

  • mcp >= 1.0.0 (FastMCP / MCP Protocol)

  • httpx >= 0.27.0 (HTTP client)

  • Pillow >= 10.0.0 (Image processing)

Development

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

# 运行测试
python -m pytest tests/

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

References

License

MIT

Available Tools

5 tools
clear_vision_cacheA

清除图片理解缓存（手动触发）

将内存中的缓存数据强制写入磁盘，并返回当前缓存统计。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It discloses that it flushes cache to disk and returns statistics, but doesn't clarify if the cache is cleared (destructive) or just persisted, leaving some ambiguity about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, focused, and front-loaded. Every word contributes meaning with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is fairly complete: it explains the action and what is returned. However, it lacks detail about the statistics returned, such as format or contents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the schema fully covers them. The description adds value by stating that the tool returns cache statistics, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool clears the image understanding cache, force writes to disk, and returns statistics. It identifies the specific resource and action, and is distinct from sibling tools like generate_image or understand_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'manual trigger' implying on-demand use, but does not provide explicit guidance on when to use this tool versus others or when not to use it. Usage is implied but not fully elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
modelNoimage-01
aspect_ratioNo1:1
response_formatNobase64
nNo
prompt_optimizerNo
save_to_diskNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It details save behavior, response_format, prompt_optimizer, and the dependency of save_to_disk on base64 mode. It omits potential latency and auth requirements, but covers core traits well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a head sentence and a list of Args. It front-loads the purpose and avoids fluff, though it repeats default values that are already in the schema. Minor redundancy barely detracts from clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, and no annotations, the description provides adequate context for prompt, model, aspect_ratio, response_format, n, and optimizer. However, it does not specify the exact output structure or error handling, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description compensates fully by explaining all 7 parameters with defaults, constraints (e.g., aspect_ratio options, n range 1-3), and mode interactions (e.g., save_to_disk only for base64). This adds significant value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it uses 'MiniMax image-01' to 'generate images' and defaults to local saving. This distinct verb-resource pairing differentiates it from siblings like 'understand_image' and 'web_search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains parameter behavior and defaults but lacks explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or specify any prerequisites, leaving usage context implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_quotaA

查询 MiniMax Token Plan 剩余额度

返回文本模型（5小时周期）和其他模型（日周期）的配额使用情况， 包括已用次数、剩余次数、使用百分比、重置时间等。

无需参数，使用 config.env 中配置的 API Key。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool uses the configured API key, returns usage info for different model types with cycles, and lists returned data like remaining times and reset times. Minor gap: no mention of error behavior or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no wasted words. First line states purpose, second elaborates on specifics, third clarifies parameterless usage. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no parameters, the description is sufficient. It covers key behavioral aspects (cycles, reset times) and configuration. Could list exact return fields, but the '等' (etc.) suffices for the scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0 parameters, baseline 4. Description adds value by stating no parameters are needed and that the tool uses the API key from config, which is informative beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries the remaining quota of the MiniMax Token Plan. It specifies verb 'query' and resource 'quota', and distinguishes from siblings like image generation or web search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for quota inquiries but does not explicitly mention when to use or when not. Siblings are distinct, so no confusion, but explicit guidance on usage context is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
image_urlYes
promptNo
modeNodetailed
use_cacheNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses caching (LRU + disk persistence), mode-specific outputs (quick ~300 words; detailed 7 dimensions), image constraints (formats, size ≤20MB), and references OpenHanako design.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections (modes, cache, args) but some redundancy (mode details in prose and bullet). Slightly verbose but still clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive: covers input, behavior, caching, output (via mode descriptions). No output schema but mode details provide sufficient completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 4 parameters explained in detail: image_url (URL/local path, formats, limit), prompt (example question), mode (values), use_cache (boolean). Schema has 0% coverage, description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states '分析图片内容' (analyze image content) with two modes (quick/detailed). Clearly distinguishes from siblings like generate_image (creation) and web_search (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use quick mode ('适合快速了解图片内容') and detailed mode ('结构化分析'). Does not explicitly exclude alternatives but context clarifies differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.0.0
    • First observedclear_vision_cache
    • First observedgenerate_image
    • First observedquery_quota
    • First observedunderstand_image
    • First observedweb_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct operation (cache clearing, image generation, quota query, image analysis, web search) with no overlap in purpose.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., clear_vision_cache, generate_image, query_quota, understand_image, web_search).

Tool Count5/5

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.

Completeness5/5

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

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/longhz/minimax-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server