minimax-image-mcp

A Model Context Protocol (MCP) server that wraps the MiniMax image generation API. Exposes a single tool, minimax_image_generate, that any MCP-compatible client (Claude Desktop, opencode, Cursor, etc.) can call to generate images from text prompts.

Table of Contents

• Why this exists

• Features

• Quickstart

• Installation

• Using via npm

• Configuration

• Usage

• API Reference

• Error Codes

• Best Practices

• Limitations

• Architecture

• Development

• Testing

• Security

• Contributing

• Built with

• License

• Acknowledgments

Related MCP server: MiniMax MCP

Why this exists

If you use an MCP-aware LLM client and want to generate images from natural-language prompts, you need a local bridge between the client and the upstream image API. This server is that bridge for the MiniMax image-01 model:

• Speaks MCP over stdio (works with any compliant client; no HTTP transport to configure)

• Validates every input with Zod before calling the API

• Handles retry with exponential backoff and AWS-style full jitter for transient errors

• Saves generated images to a directory you control, with a strict path-traversal guard

• Returns a structured output (typed, machine-readable) so LLM clients can chain tool calls reliably

• Sends optional progress notifications for long-running requests

• Exits cleanly on SIGINT/SIGTERM

Features

• Text-to-image generation from a single prompt

• Batch generation — request up to 9 images in one call (≈8× faster than 9 separate calls at the same cost)

• Aspect ratios — 1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9

• Seed-based reproducibility — same prompt + same seed ⇒ same image

• Image-to-image with character references — pass 1–5 reference image URLs

• Prompt optimization — optional auto-rewriting of the prompt server-side

• Response formats — base64 (recommended, persistent) or url (expires in 24h)

• Automatic retry on rate-limit (1002, 60s backoff) and growth-limit (2045, 30s backoff) errors

• Cross-platform — verified on Ubuntu, Windows, and macOS via the CI matrix

• Type-safe end-to-end — TypeScript strict + noUncheckedIndexedAccess, Zod schemas for input, Zod schemas for response

Quickstart

# 1. Install via npm (no build step required)
npm install -g minimax-image-mcp

# 2. Get an API key from the MiniMax dashboard, then export it
export MINIMAX_API_KEY="sk-cp-your-key-here"

# 3. Smoke-test the server
node "$(npm root -g)/minimax-image-mcp/dist/index.js"
#   → stderr: "MiniMax Image MCP server running on stdio"
#   → stdout: empty (waits for MCP frames from the client)

# 4. Configure your MCP client (examples below) and start a session

That's it. The server speaks stdio, so any MCP client can attach to node <npm-path>/minimax-image-mcp/dist/index.js. See Using via npm for the cross-platform install path and full client configs.

Installation

Prerequisites

• Node.js 18+ (Node 20 or 22 recommended; tested in CI)

• npm 9+ (ships with Node 18+)

• A MiniMax API key — request one from the MiniMax dashboard

Option A — From npm (recommended for end users)

The fastest path. No build step, no git clone. The package is published to the public npm registry as minimax-image-mcp.

# Global install (system-wide; recommended for MCP servers)
npm install -g minimax-image-mcp

# Verify the install
npm ls -g minimax-image-mcp
# minimax-image-mcp@1.0.0 <npm-global-path>

# Show the install path (used in your MCP client config)
npm root -g
# On Linux/macOS: /usr/local/lib/node_modules
# On Windows:    C:\Users\<you>\AppData\Roaming\npm\node_modules

The compiled dist/ ships with the npm tarball, so no build step is required — the package is ready to run as soon as it installs.

Option B — From source (for contributors and customization)

Use this if you want to modify the code, run the test suite, or pin to a specific unreleased commit.

git clone https://github.com/alexlivre/minimax-image-mcp.git
cd minimax-image-mcp
npm install
npm run build

The compiled output lives in dist/. Your MCP client invokes node <repo-path>/dist/index.js.

Using via npm

The recommended way to run minimax-image-mcp is via the published npm package. This section explains the cross-platform install path, then shows full client configuration for the most popular MCP clients.

1. Install the package

npm install -g minimax-image-mcp

This places the package in your global node_modules and makes the dist/index.js entry point available at a known path.

2. Find the install path

The npm global install path differs by OS. Use npm root -g to discover yours:

Tip: in the JSON examples below, replace <npm-global-root> with the path printed by npm root -g for your OS. Or use the literal path from the table.

3. Get an API key

Request a MiniMax API key from the MiniMax dashboard. Set it in your environment before launching the MCP client:

# Linux / macOS (bash, zsh)
export MINIMAX_API_KEY="sk-cp-your-key-here"

# Windows PowerShell
$env:MINIMAX_API_KEY = "sk-cp-your-key-here"

# Windows cmd
set MINIMAX_API_KEY=sk-cp-your-key-here

Never commit this key. The .gitignore covers apikey.txt and .env; rotate it immediately if you ever paste it into a file that gets pushed.

4. Configure your MCP client

The MCP client must spawn node <npm-global-root>/minimax-image-mcp/dist/index.js with MINIMAX_API_KEY in the environment. Below are complete configs for the most popular clients — all using the npm-installed path.

opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "minimax-image": {
      "type": "local",
      "command": ["node", "<npm-global-root>/minimax-image-mcp/dist/index.js"],
      "environment": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      },
      "enabled": true
    }
  }
}

Tip: if opencode is the tool you use daily, you can resolve the path with shell substitution: $(npm root -g)/minimax-image-mcp/dist/index.js. For maximum portability across machines, paste the literal path from npm root -g.

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Linux / macOS:

{
  "mcpServers": {
    "minimax-image": {
      "command": "node",
      "args": ["<npm-global-root>/minimax-image-mcp/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      }
    }
  }
}

Windows (use the Windows-specific path):

{
  "mcpServers": {
    "minimax-image": {
      "command": "node",
      "args": ["%APPDATA%\\npm\\node_modules\\minimax-image-mcp\\dist\\index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      }
    }
  }
}

Cursor

In Cursor → Settings → MCP, click Add new global MCP server and paste:

Linux / macOS:

{
  "mcpServers": {
    "minimax-image": {
      "command": "node",
      "args": ["<npm-global-root>/minimax-image-mcp/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "minimax-image": {
      "command": "node",
      "args": ["%APPDATA%\\npm\\node_modules\\minimax-image-mcp\\dist\\index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      }
    }
  }
}

VS Code (with MCP extension)

In .vscode/mcp.json (workspace) or VS Code user settings (global):

{
  "servers": {
    "minimax-image": {
      "type": "stdio",
      "command": "node",
      "args": ["<npm-global-root>/minimax-image-mcp/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-your-key-here"
      }
    }
  }
}

Other clients

Any client that supports MCP over stdio can use this server. The contract is:

• Spawn: node <path-to-server>/dist/index.js

• Env: MINIMAX_API_KEY must be set

• Stdio: server speaks MCP JSON-RPC on stdout/stdin; logs go to stderr

5. Update later

To upgrade to a new version:

npm update -g minimax-image-mcp
# or, for major versions:
npm install -g minimax-image-mcp@latest

Then restart your MCP client so it picks up the new binary. Your config (env, paths) does not need to change.

Configuration

The server reads one required environment variable:

You can also optionally set:

For ready-to-use client configuration snippets (opencode, Claude Desktop, Cursor, VS Code) — including cross-platform paths for the npm-installed binary — see Using via npm.

Usage

Once the client is configured, restart it and the minimax_image_generate tool becomes available.

Example: simple prompt

"Generate a 16:9 wallpaper of a misty mountain at sunrise."

The client will call:

{
  "prompt": "a misty mountain at sunrise, golden hour, cinematic",
  "aspect_ratio": "16:9"
}

The server returns file paths under ./output/:

{
  "id": "abc-123-def",
  "image_count": 1,
  "saved_count": 1,
  "file_paths": ["./output/misty-mountain-at-sunrise-1737000000000-1-a1b2c3d4.jpeg"]
}

Example: batch with seed for reproducibility

"Generate 4 variations of a logo concept, same seed."

{
  "prompt": "minimalist fox logo, geometric, monochrome",
  "n": 4,
  "seed": 42,
  "aspect_ratio": "1:1"
}

Running this twice with the same seed produces the same 4 images.

Example: image-to-image with character reference

{
  "prompt": "the same character in a cyberpunk city at night",
  "subject_reference": [
    { "type": "character", "image_file": "https://example.com/my-character.png" }
  ]
}

API Reference

Tool: minimax_image_generate

Input schema (ImageGenerateSchema in src/schemas.ts):

Output schema (ImageGenerateOutputSchema):

{
  id: string,                  // upstream request ID
  image_count: number,         // number of images the API returned
  saved_count: number,         // number successfully written to disk
  file_paths: string[],        // absolute or relative paths to saved JPEGs
  failures?: { index: number; error: string }[],  // per-save errors (omitted on full success)
  metadata: {
    failed_count: string,      // upstream "failed_count" (string per API)
    success_count: string,     // upstream "success_count"
  }
}

Error Codes

The tool returns errors as MCP error results with human-readable messages. Internally, the server distinguishes:

The text portion of the error result always includes a Recovery hint when one is available (e.g. "Aguarde 60s e tente novamente" for 1002).

Best Practices

• Use n=9 for batch — same total cost, ~8× faster than 9 separate calls.

• Prefer response_format='base64' — URLs returned by the API expire in 24 hours; base64 lets you persist indefinitely.

• Set timeouts appropriately in your MCP client — n=9 can take up to ~60s end-to-end; n=1 is typically ~16s.

• Avoid artificial delays between requests — the rate limiter and the client's automatic retry handle pacing.

• Use seeds for variation grids — request n=4 with the same seed and slightly different prompts to get visually consistent iterations.

• Use prompt_optimizer selectively — it improves prompt quality but adds latency and may shift semantic intent. Turn it off when you need pixel-level control.

Limitations

• Image URLs expire in 24h when response_format='url'. Use base64 for long-term storage.

• Rate limit: 10 RPM officially documented, but the real bottleneck is ~16s of model latency per request.

• No streaming — the entire image is returned in one response. For very large batches, consider chunking manually.

• Single model — only image-01 is supported. Adding models is a future enhancement.

• No image editing — this server generates new images only. Use a separate tool for inpainting or outpainting.

Architecture

┌─────────────────────┐   stdio    ┌────────────────────┐   HTTPS   ┌─────────────────┐
│   MCP client        │ ◄────────► │  minimax-image-mcp │ ◄───────► │  MiniMax API    │
│  (Claude/opencode/  │    JSON     │  (this server)     │   JSON    │  (image-01)     │
│   Cursor/...)       │    RPC     │                    │           │                 │
└─────────────────────┘            └────────────────────┘           └─────────────────┘
                                            │
                                            │ writes JPEGs
                                            ▼
                                    ┌────────────────┐
                                    │  output_dir    │
                                    │  (./output)    │
                                    └────────────────┘

Source layout:

src/
├── index.ts      # Entry point — validates env, connects stdio transport, handles SIGINT/SIGTERM
├── server.ts     # McpServer creation, tool registration, output schema, progress notifications
├── client.ts     # MiniMaxClient — fetch + retry with Full Jitter (AWS)
├── schemas.ts    # Zod schemas (input, response, output)
├── errors.ts     # MiniMaxApiError, EmptyResponseError, toErrorResult, toTextResult
├── constants.ts  # API URLs, error codes, retry delays
├── utils.ts      # Output directory resolution (path-traversal guarded), file saving, package metadata
├── utils.test.ts # 25 unit tests
├── client.test.ts # 13 unit tests (retry, jitter, exhaustion)
├── schemas.test.ts # 22 unit tests (input/output validation)
└── server.test.ts # 12 integration tests (tool callback, progress, failures)

Request flow:

1. index.ts reads MINIMAX_API_KEY and constructs a MiniMaxClient.

2. createServer(client) builds an McpServer and registers the minimax_image_generate tool with input/output Zod schemas.

3. The client sends an MCP tools/call request on stdio.

4. The server validates input, resolves output_dir (rejecting traversal), calls client.generateImage(...), saves images in parallel via Promise.allSettled, and returns a structured result.

5. The server sends optional notifications/progress to the client if a progressToken was provided in the request.

6. On SIGINT/SIGTERM, the server calls server.close() and exits cleanly.

Development

Setup

git clone https://github.com/alexlivre/minimax-image-mcp.git
cd minimax-image-mcp
npm install

Scripts

Project conventions

• Strict TypeScript. strict: true + noUncheckedIndexedAccess: true. All public types are explicit; any is forbidden at boundaries.

• Zod everywhere. Input validation, response validation, output contract — all schemas live in schemas.ts.

• No comments in code. Code is self-documenting; the only allowed comments are JSDoc on public APIs.

• Parameter properties for readonly fields. See MiniMaxClient in client.ts for the canonical pattern.

• SDK types over hand-rolled. errors.ts uses CallToolResult from @modelcontextprotocol/sdk/types.js instead of redeclaring it.

Testing

The test suite uses Vitest with v8 coverage. The CI matrix runs on Ubuntu, Windows, and macOS, across Node 20 and Node 22 — 6 combinations total.

npm test            # 72 tests, ~1.4s
npm run coverage    # report in coverage/, thresholds enforced

Coverage thresholds (enforced in CI):

Current coverage: 90% lines, 83% branches, 89% functions, 90% statements.

Security

See SECURITY.md for:

• How to report vulnerabilities (we do not file public issues)

• The trust boundary model

• Best practices for users

• What this server does and does not do

TL;DR for users:

• Never commit your API key. The .gitignore covers apikey.txt and .env, but always double-check before git add.

• Use environment variables, not hardcoded values, in your MCP client config.

• Absolute output_dir is accepted (so agents can save into the open workspace). Relative paths must stay under the process cwd. Optional MINIMAX_ALLOWED_OUTPUT_ROOTS restricts all writes.

• Rotate your API key if you suspect it has been exposed.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the workflow, style guide, commit-message convention, and PR checklist. TL;DR:

1. Fork & clone

2. Create a feature branch

3. Make focused commits (Conventional Commits)

4. Ensure npm run build && npm test && npm run lint && npm run coverage all pass

5. Open a Pull Request against main

License

MIT © 2026 Alex Santos (@alexlivre)

Built with

This project was entirely built via vibe coding using the MiniMax M3 AI model from MiniMax.

• Code generation: Every line of source code, tests, configuration, and documentation in this repository was written by MiniMax M3 in collaboration with a human project owner.

• Methodology: Vibe coding — the human described intent, requirements, and constraints; the AI generated, refactored, tested, and documented the implementation. The human reviewed, steered, and approved every change.

• AI model: MiniMax M3 (opencode-go/minimax-m3), a large language model from MiniMax, a global AI foundation model company founded in 2022.

• Image generation API: MiniMax — the upstream image-01 model that this MCP server wraps. (Same parent company as the AI model above; different product.)

If you want to build something similar with MiniMax M3, see the MCP and Zod docs — the same patterns (Zod-validated tools, stdio transport, outputSchema) compose cleanly with any domain API.

Acknowledgments

• Model Context Protocol — the open protocol that makes this server possible

• MiniMax — the image generation API

• MiniMax — the AI model and the company behind it

• OpenCode — the AI-powered CLI tool used to build, test, and maintain this project

• @modelcontextprotocol/typescript-sdk — the SDK this server is built on

• AWS Architecture Blog — Exponential Backoff and Jitter — the canonical reference for the retry algorithm used here

• Zod — runtime validation

• Vitest — testing framework

Links

• npm package: minimax-image-mcp on npm

• Source code: github.com/alexlivre/minimax-image-mcp

• Issue tracker: GitHub Issues

• Releases: GitHub Releases

• Security policy: SECURITY.md