my-minimax-mcp

English | 繁體中文 | 日本語

<p align="center"> <img src="https://raw.githubusercontent.com/wongo/my-minimax-mcp/main/assets/banner.png" alt="Token costs burning vs MiniMax workflow efficiency" width="600"> </p>

MCP server that wraps MiniMax AI as an autonomous code executor for Claude Code.

Purpose: Coding tasks consume the bulk of your Claude subscription quota on execution (writing, testing, debugging). This MCP server offloads that work to MiniMax API (~$0.04/task), so your Claude subscription handles significantly more tasks per day. Built-in savings tracking proves it with real data.

Architecture

Claude Code (Opus) ─── orchestrator
    │
    ├── minimax_generate_code    → simple code generation
    ├── minimax_agent_task       → autonomous agent loop (read → write → test → debug)
    ├── minimax_chat             → multi-turn conversation
    ├── minimax_plan             → structured JSON implementation plan
    ├── minimax_cost_report      → session cost tracking
    ├── minimax_session_tracker  → cross-session usage tracking (auto-persist on shutdown)
    ├── minimax_web_search       → web search via MiniMax Coding Plan API
    └── minimax_understand_image → image analysis via MiniMax VLM

The key feature is the agent loop: MiniMax uses function calling to autonomously read files, write code, run tests, and debug — equivalent to a Sonnet sub-agent, but without consuming Claude subscription tokens.

Tools

Tool	Description	Default Model
minimax_agent_task	Autonomous coding: read files, write code, run tests, debug loop. Supports tools: read_file, write_file, edit_file, edit_file_batch, run_bash, list_files, search_content	MINIMAX_DEFAULT_MODEL
minimax_generate_code	Generate code, optionally write to file	MINIMAX_DEFAULT_MODEL
minimax_chat	Multi-turn conversation with context preservation	MINIMAX_DEFAULT_MODEL
minimax_plan	Structured implementation plan as JSON	MINIMAX_DEFAULT_MODEL
minimax_cost_report	Session token usage and cost breakdown	—
minimax_session_tracker	Cross-session usage tracking with self-improvement modes	—
minimax_web_search	Search the web using MiniMax AI	—
minimax_understand_image	Analyze images using MiniMax VLM (JPEG/PNG/WebP, max 20MB)	—

Installation

npm install my-minimax-mcp

Setup

1. Get a MiniMax API Key

Sign up at platform.minimax.io and create an API key.

2. Install & Configure

Option A: Via npm (recommended)

npm install my-minimax-mcp

Option B: From source

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

3. Create .env

MINIMAX_API_KEY=your_api_key_here

4. Register in Claude Code

claude mcp add --transport stdio --scope user minimax -- bash /path/to/my-minimax-mcp/run-mcp.sh

Or manually edit ~/.claude/settings.json:

{
  "mcpServers": {
    "minimax": {
      "command": "npx",
      "args": ["my-minimax-mcp"],
      "env": {
        "MINIMAX_API_KEY": "your-api-key",
        "MINIMAX_DEFAULT_MODEL": "MiniMax-M2.7"
      }
    }
  }
}

Note: Use claude mcp add for the simplest setup, or edit ~/.claude/settings.json directly.

Restart Claude Code. The 8 tools will appear automatically. Verify with claude mcp list.

5. Enable Self-Improvement Loop (Optional)

npx my-minimax-mcp --init

This displays the CLAUDE.md template and creates the usage log. Copy the template to ~/.claude/CLAUDE.md to enable executor routing rules. Session tracking is automatic — the MCP server persists usage data on shutdown. See templates/setup-guide.md for details.

CLI (for debugging)

# Code generation
npx tsx src/cli.ts --task "fibonacci in Python" --language python

# Chat
npx tsx src/cli.ts --mode chat --task "explain async/await"

# Autonomous agent
npx tsx src/cli.ts --mode agent --task "fix the failing tests" --dir ./my-project

CLI runs also append to MINIMAX_COST_LOG, so --end-session and --savings-report include normal CLI usage in addition to MCP usage.

Configuration

All settings via environment variables:

Variable	Description	Default
MINIMAX_API_KEY	API key (required)	—
MINIMAX_DEFAULT_MODEL	Default model used by all MiniMax chat/plan/code/agent tools unless a per-call override is supplied	MiniMax-M2.7
MINIMAX_MAX_ITERATIONS	Agent loop max iterations	25
MINIMAX_TIMEOUT_MS	Per-task timeout	300000 (5min)
MINIMAX_BASH_WHITELIST	Additional allowed bash commands (comma-separated)	—
MINIMAX_WORKING_DIR	Base working directory for file operations; minimax_agent_task may only use this directory or a nested subdirectory	process.cwd()
MINIMAX_COST_LOG	Cost log file path	~/.claude/minimax-costs.log
MINIMAX_USAGE_LOG	Session usage log path	~/.claude/minimax-usage.jsonl
MINIMAX_SESSION_TARGET	Min MiniMax calls per session	5

Self-Improvement Loop

Usage tracking is automatic — the MCP server persists session data to ~/.claude/minimax-usage.jsonl on shutdown (SIGTERM/SIGINT). No manual start/end calls required.

Optional commands via minimax_session_tracker:

• "start" — check current mode and recent trends
• "status" — mid-session progress with trend analytics and streak info
• "end" — explicit close with root cause notes if target was missed

Modes:

• Normal: Default. Target is MINIMAX_SESSION_TARGET calls (default: 5)
• Warning: Last session missed target — prioritize MiniMax
• Forced: 2 consecutive misses — all code changes must use MiniMax

Trend analytics: The status command returns trend direction (improving/declining/stable), streak length, and actionable insights.

SessionEnd hook (optional, for fully automatic tracking):

npx my-minimax-mcp --end-session

Add to ~/.claude/settings.json hooks:

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "npx my-minimax-mcp --end-session",
        "timeout": 10
      }]
    }]
  }
}

Set MINIMAX_DEFAULT_MODEL to the highest model your Token Plan supports. All MiniMax tools inherit this value by default, and the API will reject models not available on your plan.

Failure Logging & Telemetry

Every tool call outcome (success, failure, retry) is automatically recorded to the logs/ directory — no configuration needed.

Log Files

File	Contents
logs/failures-YYYY-MM.jsonl	Failure records (error category, fingerprint, caller project)
logs/success-YYYY-MM.jsonl	Success records (tool, duration, model, iterations)
logs/retries-YYYY-MM.jsonl	Retry records (attempt count, final outcome)

Files rotate monthly. The logs/ directory is gitignored.

Error Categories (8 types)

path_invalid · sandbox_violation · edit_file_no_match · iteration_limit · api_5xx · network_timeout · auth_error · unknown

Digest Analysis

# This month's digest (7 sections)
node scripts/analyze-failures.mjs

# Specific month
node scripts/analyze-failures.mjs --month 2026-05

# Custom date range
node scripts/analyze-failures.mjs --from 2026-05-01 --to 2026-05-15

# JSON output (for machine processing)
node scripts/analyze-failures.mjs --json

Output sections: Summary (total calls / success rate), Top categories, Top fingerprints (deduplicated bugs), Per-tool, Per-caller (which project called), Retry effectiveness, Quick wins (high-frequency issues with success rate < 80%).

Environment Variable Override

Variable	Description
MINIMAX_FAILURE_LOG_DIR	Custom log directory (default: <project-root>/logs)

Token Savings Tracking

Every MiniMax call is tracked, and the savings are computed automatically. This includes normal CLI runs as well as MCP server usage. Use minimax_cost_report to see real-time savings per session, or run the CLI for cumulative reports.

Real-time (per session)

minimax_cost_report now includes a savings section:

• tokensOffloaded: Exact count of tokens MiniMax handled instead of Claude
• equivalentSonnetCalls: How many Sonnet sub-agent calls that represents
• avgTokensPerCall: Self-adaptive metric (auto-improves with more data)

Cumulative (historical)

npx my-minimax-mcp --savings-report

Shows all-time, monthly, and daily breakdowns with tool-level analysis:

=== MiniMax Token Savings Report ===

Tokens offloaded to MiniMax: 426,040 in + 161,496 out = 587,536 total
Equivalent Sonnet calls saved: ~68 (avg 8,635 tokens/call)
MiniMax API cost: $0.2468 (billed separately, not your subscription)

--- By Tool ---
  agent_task           400,254 tokens (68.1%) | 8 calls
  generate_code        144,290 tokens (24.6%) | 37 calls
  chat                  28,142 tokens (4.8%)  | 20 calls

Self-Adaptive Accuracy

The avgTokensPerCall metric adapts to your usage patterns:

• < 10 data points: Uses conservative default (8,000 tokens/call)
• 10-100 data points: Computes from all your metered calls
• 100+ data points: Uses rolling window of last 100 calls

Confidence level (LOW/MEDIUM/HIGH) is reported so you know how reliable the estimate is. The more you use MiniMax, the more accurate the savings report becomes.

Web Search & Image Understanding

These tools use MiniMax's Coding Plan API (separate from the chat completions endpoint). They are included in your Token Plan subscription at no additional per-call cost.

Web Search

minimax_web_search { query: "TypeScript MCP server tutorial" }

Returns organic results (title, link, snippet, date) and related search suggestions.

Image Understanding

minimax_understand_image {
  prompt: "Extract the business hours from this image",
  imageSource: "https://example.com/schedule.png"
}

Accepts three input types:

• HTTP/HTTPS URL: Fetched and converted to base64 automatically
• Local file path: Read from disk (supports @ prefix)
• Base64 data URL: Passed through directly

Supported formats: JPEG, PNG, WebP (max 20MB).

Features

• Max output: 65,536 tokens per response (~10,000 Chinese characters / ~50K English words)
• Think tag stripping: MiniMax <think>...</think> reasoning tags are automatically removed from all responses

Security

The agent loop runs with strict sandboxing:

• Bash whitelist: Only npm test, npx, node, tsc, eslint, pytest, go test, cargo test, etc.
• Command chaining blocked: &&, ;, | operators are rejected
• Path isolation: All file operations restricted to the working directory
• Agent working-directory boundary: minimax_agent_task can only operate inside MINIMAX_WORKING_DIR or one of its subdirectories
• Iteration cap: 25 iterations max per task (configurable)
• Timeout: 5 minutes per task (configurable)
• Token budget: 500K input tokens max per task

Cost

MiniMax API pricing (per 1M tokens):

Model	Input	Output	Best for
M2.5	$0.118	$0.99	Routine code generation
M2.7	$0.30	$1.20	Complex reasoning

Typical task cost: ~$0.04 (agent loop with 10 iterations).

Verified Test Results

Full integration test (14 MCP calls, 13 tests):

Total cost:   $0.012 (1.2 cents)
Input tokens: 38,913
Output tokens: 7,228

Test	Result
API connectivity	PASS
Code generation	PASS
Agent loop (autonomous bug fix)	PASS
Structured planning (JSON)	PASS
Multi-turn conversation	PASS
Cost tracking	PASS
Multi-file task (todo module)	PASS
Security (dangerous cmd blocked)	PASS
Routing (Opus → MiniMax, not Sonnet)	PASS
Graceful failure (max iterations)	PASS
Web search (Japanese query)	PASS
Image understanding (URL)	PASS
Image understanding (local file)	PASS

Testing

# Run all tests (148 tests)
npm test

# Run with coverage report
npm run coverage

Unit tests cover safety validation, cost tracking, file writing, server initialization, session tracking, image utilities, the Coding Plan client, the savings calculator, and the failure logging system (error classification, secrets scrubbing, telemetry, retry tracking). Coverage report uses Node.js built-in test coverage (--experimental-test-coverage).

Project Structure

src/
├── mcp-server.ts           # MCP server entry (stdio transport)
├── cli.ts                  # CLI for debugging
├── client/
│   ├── minimax-client.ts   # OpenAI SDK wrapper for MiniMax chat API
│   ├── coding-plan-client.ts # Native fetch client for Coding Plan API (web search, VLM)
│   └── types.ts            # Shared types and pricing
├── agent/
│   ├── loop.ts             # Agent loop core logic
│   ├── functions.ts        # Function definitions for MiniMax
│   ├── executor.ts         # Function call executor
│   └── safety.ts           # Whitelist, path validation, limits
├── tools/
│   ├── agent-task.ts       # minimax_agent_task
│   ├── generate-code.ts    # minimax_generate_code
│   ├── chat.ts             # minimax_chat
│   ├── plan.ts             # minimax_plan
│   ├── web-search.ts       # minimax_web_search
│   ├── understand-image.ts # minimax_understand_image
│   └── index.ts            # Tool registry
├── conversation/
│   └── store.ts            # In-memory conversation store
└── utils/
    ├── cost-tracker.ts     # Token usage and cost tracking (with session ID)
    ├── session-tracker.ts  # Cross-session usage tracking and trend analytics
    ├── file-writer.ts      # Safe file writing
    ├── image.ts            # Image to base64 data URL conversion
    ├── savings-calculator.ts # Token savings computation (self-adaptive)
    ├── failure-logger.ts   # Failure JSONL logging (scrubbing, fingerprints, monthly rotation)
    ├── telemetry.ts        # Success / retry telemetry recording
    ├── error-classifier.ts # Error classification (8 categories)
    ├── secrets-scrubber.ts # Sensitive data redaction
    └── retry.ts            # Exponential backoff retry (with onAttempt callback)
scripts/
└── analyze-failures.mjs    # Monthly failure & telemetry digest analyzer
logs/                       # Runtime JSONL files (gitignored)

Changelog

v1.5.0 (2026-05-24)

Observability improvements

• analyze-failures.mjs re-classifies stored records at read time using current rules — historical logs update automatically when classifier patterns improve
• New Section 8 "Re-classification Deltas" in digest output shows how many records were corrected vs. stored category
• network_timeout pattern extended to match "Request timed out." and "read timeout" variants (previously fell through to unknown)
• Retry telemetry now actually fires — all 5 tools (web-search, chat, generate-code, understand-image, plan) pass onAttempt to withRetry() and log failed attempts via telemetry.recordRetry(); retries-YYYY-MM.jsonl will now have data

iteration_limit diagnostics

• AgentTaskResult now includes diagnostics when reason === "iteration_limit": last 3 actions, unique files modified, stillProgressing heuristic, and a human-readable suggestion ("Retry with maxIterations=N" vs "decompose the task")
• filesChanged in iteration_limit returns is now populated from tracked writes instead of always being []
• mcp-server.ts warns to stderr when caller sets maxIterations < 10
• Iteration_limit failure log entries now include diagnostics payload for future analysis

Tests

• 161 tests (up from 152): 8 new agent-loop tests for diagnostic helpers, 1 safety regression test for cross-project resolveWorkingDirectory

v1.4.0 (2026-05-17)

Failure Logging & Telemetry

• Every tool call (success, failure, retry) is now recorded to monthly JSONL logs in logs/
• 8 error categories: path_invalid, sandbox_violation, edit_file_no_match, iteration_limit, api_5xx, network_timeout, auth_error, unknown
• Secrets scrubbing — API keys, Bearer tokens, JWTs never reach logs
• Deduplication fingerprints — identical bugs collapse into one entry
• Per-caller attribution — failures attributed to the calling project by working directory
• New scripts/analyze-failures.mjs digest with 7 sections: summary, categories, fingerprints, per-tool, per-caller, retry effectiveness, quick wins

Bug Fixes

• Fixed sandbox_violation not being captured by failure logger (validation now inside try block)
• Fixed callerProject showing as (unknown) for sandbox violations — falls back to raw input path
• Fixed MINIMAX_WORKING_DIR defaulting to minimax project dir, blocking all cross-project agent_task calls; run-mcp.sh now sets it to ~/Projects

Internals

• retry.ts: added onAttempt callback for retry telemetry
• agent/loop.ts: added reason field to AgentTaskResult (iteration_limit, timeout, task_complete, task_failed, no_tool_calls)
• 148 tests (up from 96)

v1.3.8

• Guaranteed tokensOffloaded in every session cost report
• Added savings analyzer (scripts/analyze-savings.mjs) with --diagnose and date range flags
• Hardened launcher script; failure logging foundation

v1.3.6 – v1.3.7

• edit_file fuzzy match (CRLF / trailing-space tolerant) with closest-3-lines hints on failure
• edit_file_batch for atomic multi-point edits in a single iteration
• Routing calibration: raised Sonnet threshold from 5-file to cross-cutting refactor only
• minimax_session_tracker auto-persists on shutdown (no manual end required)

License

MIT