Skip to main content
Glama
webski101
by webski101

minimax-llm-mcp

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

npm version License: MIT Node engine

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:

Tool

Purpose

minimax_chat

Non-streaming chat completion.

minimax_complete

Single-turn text completion (prompt + optional system).

minimax_tool_call

M3-native tool-use passthrough. Forwards tools and tool_choice verbatim.

minimax_count_tokens

Local token count using cl100k_base (no upstream call).

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: Test MCP Server

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 countingminimax_count_tokens runs entirely client-side via gpt-tokenizer's cl100k_base encoding; no upstream call, deterministic, fast.

  • Production-grade HTTPAuthorization: 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.

  • Testedvitest with v8 coverage; 80%+ line coverage on the runtime modules.


Installation

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.

Variable

Required

Default

Description

MINIMAX_API_KEY

yes

(none)

Bearer token for the MiniMax M3 LLM API.

TRANSPORT

no

stdio

Transport the server listens on. One of stdio or sse.

REQUEST_TIMEOUT_MS

no

300000

Per-request timeout when calling the upstream API (in milliseconds).

RETRY_ON_429

no

true

Whether to retry once on 429 Too Many Requests with a short back-off.

MINIMAX_EMBEDDING_ENABLED

no

false

Reserved for a future minimax_embed tool (out of scope in 0.1.0).

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:

Field

Type

Required

Notes

model

string

no (default: MiniMax-M3)

messages

array

yes

At least one message. Each has role (system/user/assistant/tool/function), content, and optional name / tool_call_id.

temperature

number

no

[0, 2].

top_p

number

no

[0, 1].

n

integer

no

Number of completions.

max_tokens

integer

no

≤ 1,000,000 (hard cap).

stop

string | string[]

no

presence_penalty

number

no

[-2, 2].

frequency_penalty

number

no

[-2, 2].

user

string

no

Upstream abuse-tracking identifier.

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

minimax_complete

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

Input:

Field

Type

Required

Notes

model

string

no (default: MiniMax-M3)

prompt

string

yes

Non-empty.

system

string

no

System message prepended before prompt.

(rest)

same as minimax_chat

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:

Field

Type

Required

Notes

(same as minimax_chat)

tools

array

yes

Non-empty. Each entry is the OpenAI tool object (e.g. { type: "function", function: { name, description, parameters } }).

tool_choice

string | object

no

Standard OpenAI forms: "auto", "none", "required", or {"type": "function", "function": {"name": "..."}}.

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:

Field

Type

Required

Notes

model

string

no (default: MiniMax-M3)

Recorded in the result, not used for tokenization.

messages

array

yes

At least one message.

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

Script

What it does

npm run build

Bundle src/index.ts to dist/ via tsup (CJS + .d.ts + sourcemap).

npm run dev

Same as build but with --watch.

npm run typecheck

tsc --noEmit against tsconfig.json.

npm test

Run the vitest suite once.

npm run test:watch

vitest --watch.

npm run coverage

vitest run --coverage (v8 provider; writes HTML to coverage/).

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 builddist/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.

Available Tools

4 tools
minimax_chatC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nNo
stopNo
userNo
modelNoMiniMax-M3
toolsNo
top_pNo
messagesYes
max_tokensNo
temperatureNo
tool_choiceNo
presence_penaltyNo
frequency_penaltyNo

TDQS

C2.4/5.0
Behavior2/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 only mentions non-streaming and return values, omitting details about authentication, rate limits, error handling, or whether the operation is read-only or mutable. This is insufficient for safe agent usage.

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 concise at two sentences, with no unnecessary words. However, it lacks structure and does not front-load key information like parameter usage or important constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (12 parameters, no output schema, no annotations), the description is severely incomplete. It fails to cover parameter semantics, return value details, or usage context, leaving the agent without sufficient information for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 12 parameters with 0% description coverage, yet the tool description adds no information about any parameter. For example, it does not explain the role of 'temperature' or 'messages' beyond what the schema provides. This is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a non-streaming chat completion against MiniMax M3, which is a specific verb and resource. However, it does not differentiate from sibling tools like minimax_complete or minimax_tool_call, missing an opportunity to clarify when to use this tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., minimax_complete for completions, minimax_tool_call for tool calls). The description lacks any context about prerequisites or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

minimax_completeB

Single-turn text completion against MiniMax M3. Wraps a prompt (plus optional system) into a one-message conversation and returns the assistant content.

ParametersJSON Schema
NameRequiredDescriptionDefault
stopNo
userNo
modelNoMiniMax-M3
top_pNo
promptYes
systemNo
max_tokensNo
temperatureNo
presence_penaltyNo
frequency_penaltyNo

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavioral traits. It only mentions wrapping prompt/system into a one-message conversation and returning content, but omits error handling, rate limits, permissions, or 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?

Single sentence with no redundancy, efficiently conveys core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters and no output schema, the description is too brief. Does not explain return values, parameter usage, or behavioral details beyond basic wrapping.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; description only mentions 'prompt' and 'system', ignoring 8 other parameters. Does not compensate for missing schema descriptions.

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 performs single-turn text completion against a specific model (MiniMax M3), distinguishes it from sibling tools like minimax_chat by emphasizing 'single-turn'.

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?

Implies single-turn use case but does not explicitly state when to use vs alternatives or when not to use. Sibling names hint at distinctions, but description lacks direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

minimax_count_tokensB

Local token count for a conversation using the cl100k_base BPE encoding. Returns total, model, encoding, and a per-message breakdown. Does not make a network call.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
messagesYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool is local and non-destructive, but with no annotations, it must carry the full burden. It mentions using cl100k_base encoding but does not clarify how the 'model' parameter affects behavior or if it is ignored. No error handling or edge cases mentioned.

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?

Two sentences, each carrying important information (purpose, return values, locality). No redundant words, front-loaded with the core action. Efficiently sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main purpose and return types but omits details about the 'model' parameter and does not specify constraints (e.g., maximum message size). For a tool with no output schema and two parameters, it lacks full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameters. It fails to describe either 'model' or 'messages'. The role of 'model' is unclear given the fixed encoding, and the structure of 'messages' is not explained despite being required with nested properties.

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's purpose: local token count for a conversation using cl100k_base BPE encoding. It specifies the return values (total, model, encoding, per-message breakdown) and differentiates from sibling tools (minimax_chat, etc.) by focusing on counting rather than generating.

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 notes that this tool does not make a network call, implying it is fast and local. However, it does not explicitly state when to use this tool versus the siblings or provide scenarios where counting is preferred. Lacks guidance on prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

minimax_tool_callA

M3-native tool-use passthrough. Forwards tools and tool_choice verbatim to MiniMax M3 and returns the assistant content plus any proposed tool_calls. When the upstream finishes with finish_reason 'tool_calls', the text content is a structured JSON block with the call list.

ParametersJSON Schema
NameRequiredDescriptionDefault
stopNo
userNo
modelNoMiniMax-M3
toolsYes
top_pNo
messagesYes
max_tokensNo
temperatureNo
tool_choiceNo
presence_penaltyNo
frequency_penaltyNo

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility. It explains the forwarding behavior and return content, but omits details like authentication needs, rate limits, error handling, or side effects. The description is partially transparent but leaves notable gaps.

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 long, front-loads the core purpose, and contains no redundant words. Every sentence adds essential information, achieving maximal efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters, no output schema, and no annotations, the description is insufficient. It explains the core mechanism but fails to document most parameters, return value format (beyond mentioning a JSON block), or error conditions. The agent lacks full context to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It only explains that 'tools' and 'tool_choice' are forwarded verbatim, adding value for those two parameters. However, 9 other parameters (stop, user, model, top_p, max_tokens, temperature, etc.) receive no explanation, resulting in very limited parameter context.

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 is a 'tool-use passthrough' for MiniMax M3, specifies it forwards `tools` and `tool_choice` verbatim, and returns assistant content and tool calls. This distinguishes it from sibling tools (minimax_chat, minimax_complete, minimax_count_tokens) by focusing on tool invocation.

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?

The description provides context for when to use this tool (when handling tool calls from MiniMax M3) by mentioning the finish_reason 'tool_calls' behavior. However, it does not explicitly state when not to use it or name direct alternatives, though sibling names imply the choice.

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.

  1. 4 tool updatesv0.1.0
    • First observedminimax_chat
    • First observedminimax_complete
    • First observedminimax_count_tokens
    • First observedminimax_tool_call

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: chat completion, single-turn completion, local token counting, and tool-use passthrough. No overlap or confusion.

Naming Consistency5/5

All tools follow the consistent pattern 'minimax_<action>' with snake_case, making them predictable and easy to navigate.

Tool Count5/5

4 tools is well-scoped for an LLM server, covering the essential interactions without unnecessary bloat.

Completeness4/5

Covers core LLM operations but lacks streaming support, which is a common expectation for chat completions. Otherwise sufficient.

Maintenance

ActivityInactive
ResponsivenessNo issues

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

  • F
    license
    Not graded
    quality
    Not graded
    maintenance
    Bridges STDIO-based MCP clients with SSE-based MCP servers, allowing applications like Claude Desktop to connect to remote MCP servers that use SSE transport.
    9
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    A dual-transport MCP server that exposes your API as tools to LLM clients, supporting both stdio transport for local clients like Claude Desktop and HTTP/SSE transport for remote clients like OpenAI's Responses API.
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that wraps the Gemini CLI to provide tools for executing prompts, managing chat sessions, and accessing CLI extensions. It supports both local stdio and remote SSE transports for flexible integration with MCP clients.
    1
    -
  • A
    license
    B
    quality
    D
    maintenance
    A minimal local MCP server that wraps any Claude Messages API-compatible upstream into a unified ask_model tool. It enables MCP clients to interact with these models through a standard tool interface using stdio transport.
    1
    8
    MIT