mmxomni

Model Context Protocol server for MiniMax media APIs.

Expose image generation, text-to-speech, music, and video generation from MiniMax as MCP tools. Works with any MCP-aware host: Open WebUI, Claude Desktop, Cursor, and more.

Features

Related MCP server: MiniMax MCP

Quick Start

# Run directly without installing
MINIMAX_API_KEY=sk-... npx mmxomni

# Or install globally
npm i -g mmxomni
MINIMAX_API_KEY=sk-... mmxomni

The server starts an MCP stdio transport. Your host spawns it and communicates over stdin/stdout — you do not run it interactively. See Installation below for copy-pasteable JSON blocks for your host.

Authentication

mmxomni uses the same credential precedence as mmx-cli, so existing users have nothing to reconfigure:

Region is resolved with the same precedence (--region / MINIMAX_REGION / config), defaulting to global. Region cn uses https://api.minimaxi.cn/v1.

Setting up ~/.mmx/credentials.json

{
  "MINIMAX_API_KEY": "sk-your-key-here"
}

CLI Options

mmxomni [options]

  --api-key <key>       MiniMax API key (overrides env / config file)
  --region <region>     API region: 'global' or 'cn' (default: global)
  --log-level <level>   Log verbosity: error|warn|info|debug (default: warn)
  --enable-bonus        Register bonus tools: mmx_vision_describe,
                          mmx_search_query, mmx_quota_show
  --version             Print the server version and exit
  --help                Show this help message and exit

Bonus tools can also be enabled via the MMXOMNI_BONUS=1 environment variable.

Installation

Every MCP host needs to know the command to spawn mmxomni, along with your MiniMax API key. Below are copy-pasteable config blocks for popular hosts.

The env-var pattern is the same everywhere: point the host at npx -y mmxomni with MINIMAX_API_KEY set in the environment.

Open WebUI

Open Settings → External Tools → MCP Servers → Add Server and paste:

{
  "command": "npx",
  "args": ["-y", "mmxomni"],
  "env": {
    "MINIMAX_API_KEY": "sk-your-key-here"
  }
}

For bonus tools, add "MMXOMNI_BONUS": "1" to the env block.

Claude Desktop

Edit claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

With bonus tools:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni", "--enable-bonus"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Claude Code CLI

Edit .claude/settings.json in your project root:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Codex CLI (OpenAI)

Edit ~/.codex/mcp.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Gemini CLI

Edit ~/.gemini/mcp.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Opencode CLI

Edit .opencode/mcp.json in your project root:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Cline / Roo Code (VS Code extension)

Edit .cline/mcp.json or .roo/mcp.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Continue (VS Code extension)

Edit ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "mmxomni": {
        "command": "npx",
        "args": ["-y", "mmxomni"],
        "env": {
          "MINIMAX_API_KEY": "sk-your-key-here"
        }
      }
    }
  }
}

VS Code (GitHub Copilot)

Edit .vscode/mcp.json in your project root or add to user settings.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Zed

Edit ~/.config/zed/settings.json:

{
  "mcp_servers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Windsurf

Edit .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Goose

Edit ~/.goose/config.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  mmxomni:
    command: npx
    args: ["-y", "mmxomni"]
    env:
      MINIMAX_API_KEY: sk-your-key-here

Openclaw

Edit ~/.openclaw/mcp.json:

{
  "mcpServers": {
    "mmxomni": {
      "command": "npx",
      "args": ["-y", "mmxomni"],
      "env": {
        "MINIMAX_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Generic stdio MCP entry

Any host with stdio-based MCP support uses the same shape. Configure it however the host expects:

{
  "command": "npx",
  "args": ["-y", "mmxomni"],
  "env": {
    "MINIMAX_API_KEY": "sk-your-key-here"
  }
}

Core Tools

mmx_image_generate

Generate one or more images from a text description.

Example:

"Generate an image of a red apple on a wooden table." Calls mmx_image_generate with prompt="a red apple on a wooden table".

mmx_speech_synthesize

Synthesize speech from text.

Example:

"Say 'Hello, world' in a British accent." Calls mmx_speech_synthesize with text="Hello, world".

mmx_music_generate

Generate music from a style prompt and/or lyrics.

At least one of prompt or lyrics is required. instrumental=true and lyrics are mutually exclusive.

Example:

"Create an upbeat pop song with lyrics about summer." Calls mmx_music_generate with prompt="upbeat pop" and lyrics="...".

mmx_video_generate / mmx_video_status / mmx_video_download

Async video generation in three steps, or synchronous with wait=true.

mmx_video_generate

Async mode (default) returns { task_id, status, model }. Pass wait=true to poll until Success or Fail.

mmx_video_status

Returns the raw task object with status, progress, and file URL.

mmx_video_download

Example:

"Generate a 6-second video of a cat walking on a beach." First calls mmx_video_generate with prompt="a cat walking on a beach", then mmx_video_status to poll, then mmx_video_download to save the result.

Bonus Tools

Enable with --enable-bonus or MMXOMNI_BONUS=1.

mmx_quota_show is especially useful for Token Plan users to check remaining monthly usage.

Development

git clone <repo>
cd mmxomni
npm install
npm run build    # produce dist/
npm test         # 120+ tests, no live network calls
npm run lint     # eslint

The project uses:

• TypeScript + tsup for building

• @modelcontextprotocol/sdk for the MCP server framework

• zod for tool input schema validation

• undici for HTTP requests

• vitest for testing (with undici MockAgent for offline tests)

Architecture & Design Decisions

Feature Flag with Tri-State Resolution

The --enable-bonus CLI flag uses a tri-state (undefined | true | false) to distinguish "not set" from "explicitly disabled". This allows the env var MMXOMNI_BONUS=1 to take effect when no CLI flag is passed, while --no-enable-bonus overrides the env var:

CLI --enable-bonus   → true  (bonus tools registered)
CLI not set, env=1   → true  (bonus tools registered)
CLI not set, no env  → false (core tools only)
CLI --no-enable-bonus + env=1 → false (CLI wins)

MiniMax → MCP Error Code Mapping

MiniMax API error codes are mapped to the mmx-cli exit-code convention, which aligns with MCP isError semantics:

The mapping is resolved in src/errors.ts via MmxcError.toMcpErrorCode(), which checks the MiniMax-specific code table before falling back to the HTTP status mapping.

Async Video with Polling Seam

mmx_video_generate submits a task and returns { task_id, status, model } immediately. The companion mmx_video_status tool lets the agent poll for completion. An optional wait=true flag bundles the two into a single call: the tool polls at poll_interval_seconds (default 5s) up to wait_timeout_seconds (default 600s), returning the resolved task on success/fail or a timeout error with MCP code 5. The polling loop is injectable via a sleepFn seam for zero-wait tests.

Retry with Exponential Backoff

The shared HTTP client (MmxcClient) retries 429 and 5xx responses up to 3 times with exponential backoff: baseMs * 2^attempt (default base 250ms → delays of 250ms, 500ms, 1s). 401/403/400/408 responses are never retried — they throw MmxcError immediately. The retry count is configurable via the maxRetries constructor option.

Credential Reuse from mmx-cli

The server reads ~/.mmx/credentials.json and ~/.mmx/config.json directly — the same files used by the official mmx-cli. Users who already configured the CLI need zero additional setup. Credentials resolve in strict order: --api-key flag > MINIMAX_API_KEY env > credentials file > config file.

Region-Aware Base URL

The base URL is selected by region at construction time:

• global → https://api.minimax.io/v1

• cn → https://api.minimaxi.cn/v1

An explicit --base-url override bypasses the region lookup entirely, useful for testing against staging environments.

Offline Testing with Call History

Every unit test uses undici's MockAgent with enableCallHistory() enabled. Tests assert precise HTTP attempt counts (e.g., "exactly 4 attempts for a terminal 5xx") without relying on real network calls. The smoke test is the only test that hits the live API, and it is gated behind it.runIf(process.env.MINIMAX_API_KEY) — skipped by default.

License

MIT