Last verified: August 26, 2026. Current Python and JavaScript source, CLI release state, video defaults, and live tool-count discrepancies were rechecked. Music account eligibility: August 20, 2026.
MiniMax MCP connects compatible AI clients to MiniMax speech, voice, image, and Video Generation V1 tools through the Model Context Protocol. Tool availability is package-specific: the current Python and JavaScript sources do not expose music_generation, even though MiniMax’s older platform guide still lists it.
Freshness warning: the current Python source defaults to
speech-2.8-hdandMiniMax-Hailuo-2.3, while older platform text and source docstrings still show earlier values. Its video wrapper still calls Video Generation V1 and does not expose theMiniMax-H3V2 content-array schema. Use live tool discovery for the installed package; use the official CLI or Video Generation V2 API when H3 selection must be explicit.
Independent guide: MiniMax-AI.chat is not MiniMax and does not operate the MCP packages, API, clients, or accounts described here. Commands and capabilities can change after the verification date. Check the official repository and client documentation before installation, and never paste a real API key into a public page or shared configuration.
MiniMax MCP Guide Contents
- The short answer
- MCP versus CLI versus direct API
- How MiniMax MCP works
- Python and JavaScript implementation status
- Available MCP tools
- Model-version and freshness limits
- Secure Python MCP setup
- Verification and first tests
- Practical workflows
- Costs and rate limits
- Security, privacy, and voice rights
- Troubleshooting
- Production checklist
- Frequently asked questions
The Short Answer: Should You Use MiniMax MCP?
Use the official Python MiniMax MCP server when your desktop assistant, IDE, or agent host already uses MCP and you want it to call MiniMax media tools through a standard tool interface. Start with local stdio transport, a restricted output directory, and explicit approval for billable or sensitive actions.
Use MiniMax CLI when a terminal command or agent skill is acceptable. The current CLI surface covers text, image, video, speech, vision, search, quota, configuration, and MiniMax-H3 through Video Generation V2. Release v1.0.21 retired Music CLI and SDK support, so older README or MCP recommendations that still mention Music or music cover are not current capability evidence. The CLI documentation requires a MiniMax Token Plan; confirm the current plan and account route before choosing it.
Use the direct MiniMax API for a production application that needs exact model selection, request validation, observability, authentication boundaries, predictable retries, and stable application-owned workflows. MCP standardizes tool discovery and invocation; it does not replace the API contract underneath.
Avoid choosing either MCP package from its README alone. MiniMax’s official documents and current source disagree on tool count, model defaults, and Music. Review the installed package version and discovered tool schema before enabling billable or sensitive actions.
MiniMax MCP vs CLI vs Direct API
| Option | Best for | Main advantage | Main limitation | Recommendation |
|---|---|---|---|---|
| Python MiniMax MCP | MCP-compatible desktop clients, IDEs, and local agents | Discoverable media tools through a standard protocol | Tool schemas and default model IDs can lag the API catalog | Use when MCP is a real requirement |
| MiniMax CLI | Terminal users and agents that can execute a skill or command | Broader, newer documented feature set and simpler setup | It is not an MCP server, and its current README requires a MiniMax Token Plan | MiniMax’s current recommended starting point when the plan requirement fits |
| Direct API | Web apps, backends, production pipelines, and custom products | Exact endpoint, model, validation, logging, and retry control | You build the orchestration and user experience | Best production foundation |
| JavaScript MiniMax MCP | Teams maintaining an existing JS integration or needing its extra transports | Documents stdio, REST, SSE, and a JS-only image-to-video tool | Public configuration and model notes are visibly older | Audit and test before use; do not copy it blindly |
If your goal is simply to call MiniMax from application code, read the MiniMax API guide. Adding MCP between your application and the API creates another versioned component and does not automatically improve quality, price, privacy, or reliability.
How MiniMax MCP Works
The Model Context Protocol is an open protocol for connecting an AI application to external resources and executable tools. In a MiniMax setup, the components have separate responsibilities:
- Host: the application the user interacts with, such as an MCP-capable assistant or IDE.
- MCP client: the connector inside that host. It starts or connects to the configured server and discovers its declared capabilities.
- MiniMax MCP server: the local or hosted wrapper that exposes functions such as
text_to_audioandgenerate_video. - MiniMax API: the external service that performs the generation after the MCP server sends an authenticated request.
- Output location: a local directory or returned URL, depending on resource mode and tool behavior.
MCP does not mean a MiniMax model runs locally. With the official server, the generation request still goes to a MiniMax API host and can consume paid quota. A local stdio server keeps the MCP transport on the machine, but prompts, uploaded media, and other request data required for generation still leave the machine for the API.
The host may allow a language model to choose when to call a discovered tool. That is convenient, but it also means the host’s approval settings, the tool description, the conversation context, and untrusted content can affect a billable external action. Keep human confirmation enabled for voice cloning, media uploads, high-cost generation, and any action that writes files.
Official MiniMax MCP Implementations
| Implementation | Package or command | Current source status checked August 26, 2026 |
|---|---|---|
| Python | uvx minimax-mcp; repository package version 0.0.19 | The README lists seven tools; server.py registers eight because it also includes play_audio. Current source does not register music_generation. |
| JavaScript/TypeScript | minimax-mcp-js; repository package version 0.0.18 | The official repository retired its Music MCP tool and removed the related documentation on August 20, 2026. Review transports, hosts, and the installed schema before deployment. |
Source-conflict rule: MiniMax’s platform MCP guide still lists ten tool names. The Python README lists seven, while the current Python source registers eight. Live MCP discovery is authoritative for what an installed server advertises; a guide or README is not proof that a particular tool exists in your package or that your account may call it.
Python Implementation: Inspect Source and Discovery Together
The current Python README and official MCP guide align on the current regional hosts: global accounts use https://api.minimax.io, and Mainland China accounts use https://api.minimaxi.com. The key and host must belong to the same region.
Current Python source defaults to speech-2.8-hd and MiniMax-Hailuo-2.3. Some platform copy and source docstrings still show older speech or Hailuo-02/01-era values. More importantly, the wrapper uses Video Generation V1; changing a model string does not add the V2 request schema required by H3.
JavaScript Implementation: Music Was Retired
The JavaScript repository is official, not a community fork. Its current commit history records the August 20, 2026 retirement of the Music MCP tool and removal of the related source and documentation. Do not copy an older JavaScript README, cached search result, or 2025 article that still presents Music 1.5 as a current tool.
For either implementation, compare the package version, current source, client-discovered schema, and one controlled test account. Never silently replace a host or model in old sample code and assume the rest of the request contract is compatible.
Current Python MCP Tools and Documentation Gaps
| Tool | Purpose | Boundary |
|---|---|---|
text_to_audio | Convert text to speech | Current source defaults to speech-2.8-hd; confirm any explicitly selected model. |
list_voices | List available voices | Results can vary by account, region, and voice type. |
voice_clone | Create a reusable voice from authorized audio | Obtain speaker consent and protect voice samples. |
voice_design | Design a synthetic voice from text | A designed voice is different from cloning a real person. |
play_audio | Play a local file or URL | Registered in current Python source but omitted from its seven-tool README summary. |
generate_video | Create a V1 video task | Current source defaults to Hailuo 2.3, but the wrapper does not expose H3 Video Generation V2. |
query_video_generation | Poll an asynchronous video task | Handle timeouts, failed terminal states, and expiring output URLs. |
text_to_image | Generate images | The documented model is Image-01; inspect output mode and URL retention. |
The platform guide also lists image_to_video and music_generation. Those entries explain the historical ten-tool count; they do not make the tools appear in the current Python source. The current JavaScript source also no longer exposes Music. Use live discovery rather than combining tool lists from different versions.
Current Models vs MCP Defaults
| Capability | Verified current position | Correct route |
|---|---|---|
| Text and vision | The media-focused MCP server does not document a general MiniMax M3 chat tool. | Use MiniMax CLI or the direct language-model API. |
| Speech | Current Python source defaults to speech-2.8-hd; older guide text still shows speech-02-hd. | Inspect the installed schema and send a supported explicit model when available. |
| Video | Current Python source defaults to MiniMax-Hailuo-2.3 through V1. It does not expose the H3 V2 content array. | Use MiniMax CLI or Video Generation V2 for MiniMax-H3. |
| Image | The MCP source and docs align on Image-01, subject to package-specific parameters. | MCP is reasonable after a controlled test call. |
| Music | The platform guide still documents music_generation, but current Python and JavaScript sources do not expose it. Paid API access is also closed to new users; eligible existing paying users must verify entitlement. | Do not promise MCP or CLI Music. Use only a currently entitled direct API account, MiniMax Audio, or the open-weight Music 3 model as appropriate. |
This distinction prevents a common error: platform support is not wrapper support. Read our MiniMax H3 guide for V2 video, the Hailuo 2.3 guide for the legacy family, and the MiniMax Music 3.0 guide for open-weight and hosted-access boundaries.
Secure Python MiniMax MCP Setup
The following setup uses the global MiniMax API and local stdio transport. It is a client-agnostic template based on the official Python configuration. Your MCP host may use a different settings page or configuration filename.
1. Prepare the Account, Runtime, and Output Directory
- Create an API key in the official MiniMax Developer Platform for the correct region.
- Install
uvfrom its official instructions so theuvxcommand is available. - Confirm that your host supports local MCP servers using
stdio. - Create a dedicated output directory that contains no unrelated personal or project files.
- Set spending limits or alerts before allowing an agent to call billable generation tools.
uvx --version
mkdir -p "$HOME/minimax-mcp-output"On Windows, create a dedicated folder manually and use its absolute path. If the client cannot find uvx, run (Get-Command uvx).source in PowerShell or which uvx on macOS/Linux, then place that absolute executable path in the command field.
2. Add the MCP Server to Your Client
Replace both placeholders. Use a real absolute output path, not ~, if your client does not expand shell shortcuts. The example selects local resource mode so generated files are saved into the restricted directory.
{
"mcpServers": {
"MiniMax": {
"command": "uvx",
"args": ["minimax-mcp"],
"env": {
"MINIMAX_API_KEY": "REPLACE_WITH_YOUR_MINIMAX_API_KEY",
"MINIMAX_MCP_BASE_PATH": "/absolute/path/to/minimax-mcp-output",
"MINIMAX_API_HOST": "https://api.minimax.io",
"MINIMAX_API_RESOURCE_MODE": "local"
}
}
}
}The official examples place the key in the client configuration because a locally launched stdio server needs a credential. If your host supports secret references or environment-variable inheritance, use that mechanism instead of storing the value directly in a JSON file. Restrict file permissions and exclude the configuration from backups, screenshots, support bundles, and source control.
3. Choose Local or URL Resource Mode
| Mode | Behavior | Use it when | Risk to manage |
|---|---|---|---|
local | Downloads supported generated resources to the configured path | A local client needs durable files and the folder is controlled | Disk growth, sensitive media at rest, file permissions, and cleanup |
url | Returns hosted resource URLs where supported | The client can consume URLs and local persistence is unnecessary | Link expiry, accidental sharing, referrer leakage, and later unavailability |
Resource mode is not a privacy guarantee. In either mode, the API processes the request. The setting primarily changes how the generated artifact is returned after processing.
4. Keep the Region and Key Aligned
| Platform region | Python MCP API host | Credential |
|---|---|---|
| Global | https://api.minimax.io | Key created on the global MiniMax Developer Platform |
| Mainland China | https://api.minimaxi.com | Key created on the mainland platform |
Do not infer the correct host from the user’s physical location alone. Use the region of the platform account that issued the key.
5. Restart and Review Discovered Tools
Save valid JSON, fully restart the host, and open its MCP or developer panel. Confirm that the MiniMax server starts and inspect the tool list before asking the model to call anything. A current client should show only the functions actually advertised by the installed package.
Verify the Installation Before Generating Media
- Runtime check: confirm
uvx --versionworks in the same user account that launches the client. - Server check: verify the client reports the MiniMax server as connected rather than merely saved.
- Discovery check: record the live tool names and parameters. Compare them with the official docs, but trust the installed schema for what can be invoked.
- Low-cost check: make one short, non-sensitive speech or image request using a test prompt you are permitted to send.
- Output check: confirm the file appears only in the intended directory or that the returned URL behaves as expected.
- Usage check: inspect your MiniMax account usage or quota after the request. Do not assume a successful client response was free.
- Failure check: test how the host displays a rejected parameter or unavailable model before delegating longer workflows.
A prompt such as “List the MiniMax tools available to you; do not call any tool” tests discovery without starting a generation. Then ask the host to show the exact arguments it intends to submit and require confirmation before the first billable call.
Practical MiniMax MCP Workflows
Draft-to-Narration
- Write and fact-check a short script in the host.
- Remove secrets, personal data, and text you lack permission to process.
- Ask the host to call
list_voiceswithout generating audio. - Select a voice and preview a small excerpt with
text_to_audio. - Review pronunciation, pace, and cost before synthesizing the full script.
Keep model selection explicit where the tool accepts it. The installed default may be older than Speech 2.8. For a production narration pipeline, use the direct API so the application can validate the model, chunk long text, collect usage, and retry only failed segments.
Storyboard-to-Image or Video
- Convert the concept into a shot list with one prompt, framing choice, and continuity note per shot.
- Generate a low-cost reference image first when visual direction is uncertain.
- Review logos, faces, text, brands, and ownership before using an image as a video input.
- Submit one video task and keep its task ID if asynchronous mode is used.
- Query at a sensible interval rather than repeatedly flooding the status endpoint.
- Download, label, and archive the accepted output together with its prompt and model metadata.
If the installed MCP schema exposes only the documented Hailuo-02 and 01-series IDs, treat it as a V1/legacy video wrapper. Do not relabel its output as H3. For a new H3 workflow, use Video Generation V2 directly—or a wrapper whose discovered schema explicitly accepts MiniMax-H3 and the V2 content array. If an older Hailuo or S2V ID is an intentional compatibility requirement, record that decision and keep its limits separate from H3.
Legacy Music Documentation and Current Boundary
MiniMax’s older platform MCP guide documents a prompt-and-lyrics music_generation interface, but the current Python and JavaScript sources do not expose that tool. Do not write a current workflow around a tool your installed server does not discover. Eligible existing API customers should use the current direct operation reference and verify the returned model; new users should not be promised hosted Music access.
- Use original or licensed lyrics; a user prompt does not grant rights to copyrighted lyrics.
- Describe genre traits, tempo, arrangement, mood, and structure without requesting deceptive imitation.
- Store the prompt, lyrics source, date, model evidence, and output license context with the file.
- Review distribution-platform rules before monetizing or registering generated music.
MCP Costs, Quotas, and Rate Limits
The MCP package is open-source under the MIT license, but calls to MiniMax services can be billable. MCP is an integration layer; it is not a free-generation plan. Billing depends on the API resource, account, region, model, request parameters, and current pricing.
- Review MiniMax pricing and the official pricing page before testing.
- Start with one request, one output, short duration, and a low-risk resolution or sample length.
- Require approval before the host retries a failed media generation.
- Log the tool name, timestamp, task ID, selected model when available, and final status.
- Apply a maximum retry count with backoff for rate limits and transient failures.
- Monitor quota outside the conversation; the model’s estimate is not an invoice.
MiniMax publishes route-specific video limits. The V1 Video Generation row for the Hailuo series lists 5 RPM on the free tier and 20 RPM on the paid tier. The MiniMax-H3 Video Generation V2 row instead lists CONN—maximum concurrent tasks—at 2 for the free tier and 15 for the paid tier. RPM and CONN measure different constraints. Apply the row matching the endpoint the installed tool actually calls; the published MCP video schema maps to V1 IDs, not H3 V2. Keep bounded retries and handle 429 responses rather than hard-coding these figures as permanent.
Security, Privacy, and Voice-Rights Checklist
MCP can expose executable tools to a model, so the security boundary is larger than a normal chat box. The protocol specification emphasizes user consent, data control, privacy, and explicit approval before tool invocation. Apply those principles to the host, the local server, the MiniMax API, and every input or output location.
Protect the API Key
- Do not place a live key in a prompt, screenshot, Git repository, browser bundle, or shared dotfile.
- Prefer a secret manager or client-supported environment reference.
- Restrict configuration-file permissions and rotate the key after exposure.
- Use separate development and production credentials with attributable usage.
- Treat the documented SSE and REST modes as remote, backward-compatible, or implementation-specific surfaces. For HTTP transport, validate the
Originheader, bind local-only servers to127.0.0.1, and require appropriate authentication, authorization, and TLS before any remote exposure.
Treat Tool Calls as Actions, Not Answers
Untrusted documents, web pages, repository text, or pasted instructions can attempt to manipulate an agent into calling tools. Keep confirmations enabled, display parameters before execution, allow only the required MiniMax tools, and avoid automatic retries. A model saying that an action is safe is not authorization.
Restrict Files and URLs
- Point the server to a dedicated empty output directory, not a home folder, source repository, or shared drive root.
- Do not send local files solely because the host can access them. Confirm relevance, ownership, and sensitivity.
- Use allowlisted input domains for remote workflows and guard against internal or metadata-service URLs.
- Scan generated or downloaded files before moving them into another automated pipeline.
- Define retention and deletion rules for voice samples, generated media, prompts, and task logs.
Obtain Verifiable Voice Consent
Use voice_clone only when the speaker has knowingly authorized the recording, the cloning purpose, the users, the channels, and the retention period. Do not clone a public figure, customer, employee, performer, child, or private individual merely because an audio file is online. Add disclosure where the result could reasonably be mistaken for a real recording, and never use a cloned voice for impersonation, fraud, bypassing authentication, or fabricated endorsement.
Review the sensitive-data checklist and your applicable law and contracts. This guide is technical information, not legal advice.
MiniMax MCP Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
spawn uvx ENOENT | The host cannot find the uvx executable | Run which uvx or (Get-Command uvx).source, then use the absolute path and restart the host |
| Invalid API key | Key/host region mismatch, a damaged credential, or wrong environment variable | Match global with api.minimax.io or mainland with api.minimaxi.com; rotate if exposed |
| No tools found | Server failed to start, client cached discovery, or configuration is in the wrong file | Inspect host logs, validate JSON, restart completely, and test uvx in the same user environment |
| Permission denied or no output file | Output path does not exist or is not writable | Use an absolute dedicated directory and give only the launching user required permissions |
| Model not supported | The MCP wrapper’s model allowlist lags the API catalog | Use a model exposed by the installed tool, update carefully, or switch to CLI/direct API |
| Video request appears stuck | The generation is asynchronous or the client stopped polling | Preserve the task ID, call the query tool at a reasonable interval, and handle failed/expired states |
| Returned URL no longer works | Generated resource URL expired | Download accepted outputs promptly and retain provenance according to policy |
429 or throttling | Model/account rate limit or concurrent request limit | Back off with jitter, reduce concurrency, avoid duplicate retries, and inspect the current official limits |
| Unexpected bill | The host invoked or retried a paid tool more than expected | Enable approvals, log task IDs, cap retries, set alerts, and separate test credentials |
| JS config fails with current key | Older hosts or request schemas in the JavaScript package | Do not guess a partial fix; inspect the package source/issues or move to Python MCP, CLI, or direct API |
Production Readiness Checklist
- Need: document why MCP is preferable to CLI or direct API for this workflow.
- Version: pin and record the MCP package version; review updates before rollout.
- Schema: snapshot the discovered tool names, arguments, and accepted model IDs.
- Region: verify that account, credential, API host, billing resource, and data requirements align.
- Secrets: keep keys outside prompts and source control; rotate and audit them.
- Transport: prefer local
stdio; authenticate and authorize any remote deployment. - Approvals: require human confirmation for uploads, cloning, file writes, and billable calls.
- Storage: isolate the output directory and define retention for inputs, outputs, and logs.
- Rights: verify consent and licenses for voices, faces, music, lyrics, images, and source videos.
- Costs: set budgets, request caps, concurrency limits, alerts, and bounded retries.
- Reliability: handle timeouts, task polling, expired URLs, partial failures, cancellation, and rate limits.
- Observability: log tool, model evidence, parameters excluding secrets, task ID, latency, and final status.
- Testing: run non-sensitive low-cost tests and a deliberate failure before user rollout.
- Fallback: define when the workflow should switch to the direct API or stop for manual review.
MiniMax MCP FAQ
Is MiniMax MCP official?
Yes. MiniMax publishes official Python and JavaScript implementations under the MiniMax-AI GitHub organization and documents both on its developer platform. Official ownership does not guarantee that every implementation and model default is synchronized with the newest API release.
Is MiniMax MCP free?
The server code is available under the MIT license, but MiniMax API calls may consume paid balance, subscription quota, or another billing resource. Check the account and current pricing before running a tool.
Does MiniMax MCP run the models locally?
No. A local MCP server can use local stdio transport and save outputs locally, but it sends generation requests to a MiniMax API host. Local transport is not the same as local inference.
Does current MiniMax MCP expose a music tool?
Not in the current Python or JavaScript source checked August 26, 2026. MiniMax’s platform guide still lists music_generation, which creates a documentation conflict. Trust live discovery for the installed server. Even a historical tool entry would not prove Music 3.0 selection or account entitlement.
Can the published MiniMax MCP video tool use MiniMax H3?
No. Current Python source defaults to MiniMax-Hailuo-2.3, but its wrapper still uses Video Generation V1 and does not expose the H3 V2 content array. Use the official MiniMax CLI or Video Generation V2 API for H3, and record the actual model returned.
Can MiniMax MCP still use older Hailuo models?
The published schema lists Hailuo-02 and several 01-series IDs, including S2V-01. Those are V1-era workflows. Verify the installed package, account access, and exact endpoint; apply the Hailuo-series RPM limit rather than H3’s V2 concurrency limit.
Should I use the Python or JavaScript MCP server?
For a new MCP-specific setup, start with Python because its current host table matches the present API domains. Consider JavaScript only after auditing the package and accepting its older documented hosts, models, and extra transport surface.
Why does MiniMax recommend the CLI?
The CLI is the shorter route when you need text, image, video, speech, vision, search, quota, or H3 without MCP tool discovery. It requires the documented account or Token Plan route. Music and music cover were retired from the CLI in v1.0.21, so they are not a reason to choose it.
Can I expose the MCP server over SSE?
The Python documentation lists SSE, and the JavaScript documentation lists SSE and REST in addition to stdio. However, MCP 2025-11-25 standardizes stdio and Streamable HTTP; the older HTTP+SSE transport is deprecated, and REST is implementation-specific rather than a named standard MCP transport. Test client compatibility. Any remote server needs network isolation, Origin validation for HTTP, authentication, authorization, TLS, per-user controls, auditing, and protection from arbitrary file or URL access. Do not expose the example server publicly by default.
Can I use voice cloning for client or creator work?
Only with adequate rights and specific, verifiable consent covering the clone and intended use. Provider access does not grant a right to copy a person’s voice, and local law, employment terms, union rules, contracts, and platform policies may add requirements.
Official Sources and Further Reading
- MiniMax MCP guide and tool parameters
- Official Python MiniMax MCP repository
- Official JavaScript MiniMax MCP repository
- Official MiniMax CLI repository
- Current MiniMax model catalog
- Official MiniMax H3 Video Generation V2 reference
- Official MiniMax rate limits
- Official MiniMax pricing overview
- Latest Model Context Protocol specification and safety principles
- Current MCP transport specification
Conclusion: MiniMax MCP remains a useful official bridge for MCP-native clients, especially for speech, voice, image, and older documented video workflows. As of August 13, 2026, use Python if MCP is essential; otherwise follow MiniMax’s recommendation and evaluate the current CLI. For H3, choose the direct V2 API unless the installed wrapper’s live schema explicitly exposes H3 and its V2 content array.