Skip to main content
Glama
deenesjakoruzh
longhz

MiniMax MCP Server

by longhz
OverviewSchemaSourceRelated ServersScoreDiscussions
Python
Local

MiniMax MCP Server

MiniMax Token Planのクォータ照会、Web検索、画像理解、画像生成の4つの機能を備えたフル機能のMiniMax Token Plan MCP Serverです。Python FastMCPに基づいて構築されており、Claude CodeなどのMCP対応クライアントに直接統合できます。

機能概要

ツール

機能

使用するMiniMax API

query_quota

Token Planの各モデルの残りクォータを照会

/v1/token_plan/remains

web_search

MiniMax Web検索

/v1/coding_plan/search

understand_image

画像理解（デュアルモード + キャッシュ）

/v1/coding_plan/vlm

generate_image

画像生成（image-01モデル）

/v1/image_generation

clear_vision_cache

視覚分析キャッシュのクリア

-

Related MCP server: Kimi Coding 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 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 — Web検索

MiniMax検索エンジンを通じてWebコンテンツを検索します。

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の設計思想を参考に、2つの分析モードを提供します。

設計思想：

  • 画像を専門の視覚モデル（MiniMax VLM）に渡し、構造化分析を行う

  • 分析結果をテキストとしてLLMのコンテキストに注入し、純粋なテキストモデルでも画像の内容を「理解」できるようにする

  • LRUキャッシュ（256エントリ、ディスク永続化）を内蔵し、同じ画像+同じプロンプトではクォータを重複消費しない

デュアルモード：

モード

適用シーン

出力形式

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 に保存

  • キャッシュキー：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 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