Skip to main content
Glama
deenesjakoruzh
longhz

MiniMax MCP Server

by longhz
OverviewSchemaSourceRelated ServersScoreDiscussions
Python
Local

MiniMax MCP 서버

할당량 조회, 웹 검색, 이미지 이해 및 이미지 생성의 네 가지 기능을 제공하는 완전한 기능을 갖춘 MiniMax Token Plan MCP 서버입니다. Python FastMCP를 기반으로 구축되었으며, Claude Code와 같이 MCP를 지원하는 클라이언트에 직접 통합할 수 있습니다.

기능 개요

도구

기능

사용되는 MiniMax API

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 획득

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 — 웹 검색

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개 항목, 디스크 영구 저장), 동일한 이미지 + 동일한 프롬프트는 할당량을 중복 소모하지 않음

이중 모드:

모드

적용 시나리오

출력 형식

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

참고

라이선스

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