Skip to main content
Glama
deenesjakoruzh
longhz

MiniMax MCP Server

by longhz
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MiniMax MCP Server

Полнофункциональный MCP-сервер для MiniMax Token Plan, предоставляющий четыре возможности: запрос квот, веб-поиск, анализ изображений и генерация изображений. Построен на базе Python FastMCP и может быть напрямую интегрирован в клиенты, поддерживающие MCP, такие как Claude Code.

Обзор функций

Инструмент

Функция

Используемый API MiniMax

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

Очистка кэша визуального анализа

-

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

Получите свой API Key на странице Token Plan платформы MiniMax.

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

Добавьте в конфигурацию MCP для Claude Code:

{
  "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 — Анализ изображений

Используя концепцию дизайна Vision Bridge из OpenHanako, предоставляются два режима анализа.

Концепция дизайна:

  • Передача изображения специализированной визуальной модели (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 не поддерживает вывод координат, поэтому возможность аннотации пространственных координат Visual Primitives из OpenHanako пока не реализована. Если вам нужен анализ изображений с учетом координат, рекомендуется использовать модели, поддерживающие визуальные примитивы.

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

Ссылки

Лицензия

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