minimax-llm-mcp

An MCP server that exposes the MiniMax M3 LLM API to MCP-compatible clients.

MCP server that exposes the MiniMax M3 LLM API to MCP-compatible clients over stdio and SSE.

Overview

minimax-llm-mcp is a Model Context Protocol (MCP) server that exposes the MiniMax M3 LLM API to any MCP-compatible client — Claude Desktop, Cursor, CyOps, Windsurf, and others. The server speaks JSON-RPC over stdio (the default, suitable for child-process clients) and HTTP + Server-Sent Events (SSE, for browser- and network-based clients), and registers four tools that map cleanly onto the upstream's chat-completions and tool-use surface:

The MiniMax M3 endpoint is OpenAI-compatible; the server wraps a small, well-tested HTTP client that handles auth, timeouts, retry-on-429, error mapping, and request-secret redaction.

Status: 0.1.0 — the binary, the four tools, and the stdio + SSE transports are wired up. The SSE transport is feature-complete but not exercised by the demo at this time.

Related MCP server: MCP SSE Proxy

Features

• MCP-native — registers four tools with Zod-validated input schemas, conforming to the MCP spec.

• Two transports — stdio (default) for child-process clients, and HTTP+SSE for network clients.

• OpenAI-compatible — non-streaming and streaming chat completions, plus native tool-use passthrough.

• Local token counting — minimax_count_tokens runs entirely client-side via gpt-tokenizer's cl100k_base encoding; no upstream call, deterministic, fast.

• Production-grade HTTP — Authorization: Bearer … on every request, configurable per-request timeout, one-shot retry on 429 with exponential backoff, and full HTTP-status → McpError mapping (401/403 → AuthenticationRequired, 429 → RateLimited, 5xx → UpstreamError, other 4xx → InvalidRequest).

• Secret redaction — error messages are scrubbed of sk-… API-key shapes before they leave the server.

• TypeScript-native — strict ES2022 / NodeNext / tsup-bundled CJS with declarations on the wire.

• Tested — vitest with v8 coverage; 80%+ line coverage on the runtime modules.

Installation

From npm (recommended)

npm install -g minimax-llm-mcp

This installs the minimax-llm-mcp binary on your PATH, ready for any MCP client to spawn.

From a local checkout

git clone https://github.com/your-org/minimax-llm-mcp.git
cd minimax-llm-mcp
npm install
npm run build

The compiled binary is then at ./dist/index.js. Point your MCP client at it directly (see Usage below).

Prerequisites

• Node.js ≥ 18 (the engines field enforces this).

• A MiniMax API key. Sign up at the MiniMax developer portal and copy the bearer token from your dashboard.

Configuration

The server reads its configuration from environment variables at startup. The schema is validated by Zod; missing or invalid values produce a ConfigError and exit 1 on stdio, or 500 on SSE.

The full set is also documented in .env.example — copy that file to .env and uncomment the lines you want to override:

cp .env.example .env
$EDITOR .env

Usage

The server is consumed by an MCP client. Below are copy-pasteable configuration snippets for the four most common clients. Replace <your-minimax-api-key> with a real bearer token, or set MINIMAX_API_KEY in the client's environment.

Claude Desktop

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

{
  "mcpServers": {
    "minimax-llm-mcp": {
      "command": "npx",
      "args": ["-y", "minimax-llm-mcp"],
      "env": {
        "MINIMAX_API_KEY": "<your-minimax-api-key>"
      }
    }
  }
}

Or, if you have a local build:

{
  "mcpServers": {
    "minimax-llm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/minimax-llm-mcp/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "<your-minimax-api-key>"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (or use Settings → MCP → Add new global MCP server):

{
  "mcpServers": {
    "minimax-llm-mcp": {
      "command": "npx",
      "args": ["-y", "minimax-llm-mcp"],
      "env": {
        "MINIMAX_API_KEY": "<your-minimax-api-key>"
      }
    }
  }
}

CyOps

CyOps reads MCP servers from its global config (~/.cyops/mcp.json or the in-app Settings → MCP panel):

{
  "mcpServers": {
    "minimax-llm-mcp": {
      "command": "npx",
      "args": ["-y", "minimax-llm-mcp"],
      "env": {
        "MINIMAX_API_KEY": "<your-minimax-api-key>"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (or the in-app Settings → Cascade → MCP Servers → Add server form):

{
  "mcpServers": {
    "minimax-llm-mcp": {
      "command": "npx",
      "args": ["-y", "minimax-llm-mcp"],
      "env": {
        "MINIMAX_API_KEY": "<your-minimax-api-key>"
      }
    }
  }
}

Trying it without an MCP client

For a quick smoke test (no real API call required):

# In one terminal, run the server in stdio mode and pipe a JSON-RPC
# `tools/list` request through it:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | MINIMAX_API_KEY=demo-key npx minimax-llm-mcp

The server reads the request from stdin, dispatches it, and writes the JSON-RPC response to stdout. You should see the four tool names listed.

Available Tools

Every tool's input is validated by a Zod schema; the SDK applies the schema before the handler runs.

minimax_chat

Non-streaming chat completion. Returns the assistant content plus optional usage.

Input:

Output: { content, finish_reason, model, usage? }.

minimax_complete

Single-turn text completion. Wraps prompt (plus optional system) into a one-message conversation.

Input:

Output: { content, finish_reason, model, usage? }.

minimax_tool_call

M3-native tool-use passthrough. Forwards tools and tool_choice to the upstream verbatim — the server does not validate or transform the function definitions.

Input:

Output: { content, finish_reason, model, usage?, tool_calls?, tool_call_payload? }. When finish_reason === "tool_calls", tool_call_payload is a structured JSON block with the call list — it is the JSON-serialized text content the MCP client renders.

minimax_count_tokens

Local token count using the cl100k_base BPE encoding (the same one OpenAI's tiktoken uses for GPT-3.5/4). Does not make an upstream call — entirely client-side.

Input:

Output: { total, model, encoding, per_message: [{ role, tokens }] }. The counts are deterministic and match gpt-tokenizer's cl100k_base encoding.

Development

Setup

git clone https://github.com/your-org/minimax-llm-mcp.git
cd minimax-llm-mcp
npm install

Scripts

Project layout

src/
├── index.ts                # CLI entry point (stdio)
├── server.ts               # MCP server: registers the four tools
├── client.ts               # MiniMax M3 HTTP client (auth, retry, error mapping)
├── config.ts               # Zod-validated env config
├── errors.ts               # McpError factory + ErrorCategory
├── tools/
│   ├── chat.ts             # minimax_chat
│   ├── complete.ts         # minimax_complete
│   ├── tool-call.ts        # minimax_tool_call
│   └── count-tokens.ts     # minimax_count_tokens
└── transports/
    ├── stdio.ts            # startStdioServer(config)
    └── sse.ts              # startSSEServer(config, options)

tests/                      # Mirror of src/, plus a top-level suite
                            # for the server, the HTTP client, the
                            # SSE transport, and the error helpers.

TDD workflow

The slices were added in this order: scaffold → config → errors → client → count-tokens → chat → complete → tool-call → server → stdio → SSE. Each slice added the source file(s), the matching tests/.../*.test.ts, and was verified with npm test + npm run coverage before moving on. When adding a new tool or transport, follow the same pattern: write a failing test, write the engine, run the suite.

Adding a new tool

1. Create src/tools/<name>.ts with a Zod input schema, an X_INPUT_SCHEMA export, and a handleX(client, input, signal?) function. The handler returns a typed result object; the SDK wraps it in { content: [{ type: "text", text: ... }] }.

2. Create tests/tools/<name>.test.ts with vi.fn()-based client stubs.

3. Register the tool in src/server.ts via server.registerTool(name, { description, inputSchema: X_INPUT_SCHEMA.shape }, async (args) => { ... }).

Adding a new env var

1. Add a Zod schema entry to CONFIG_SCHEMA in src/config.ts (with a default if optional).

2. Add the uncommented placeholder to .env.example.

3. Add tests in tests/config.test.ts covering the validation paths.

Publishing

The package is npm publish-ready out of the box (the bin entry, files whitelist of ["dist"], engines, main, types, and license are all wired up). A pre-publish checklist:

1. Bump version in package.json.

2. npm run typecheck — clean.

3. npm test — 100% green; coverage ≥ 80% on src/.

4. npm run build — dist/index.js has the shebang and is executable.

5. npm pack — inspect the tarball. The package field should include only dist/, package.json, and README.md.

6. npm publish --dry-run — confirm the publish plan.

7. npm login (one-time).

8. npm publish — tag with latest for production releases.

The pre-publish step in CI should also npm install in a clean checkout and npm test to catch any drift between the test environment and the publish artifact.

License

MIT — Copyright (c) 2026 minimax-llm-mcp contributors.

See LICENSE for the full text.