Mimo Executor ZL MCP

Mimo Executor ZL MCP is a local Model Context Protocol server for delegating executor-only work to a Mimo-compatible model route.

It is designed for a controller model such as DeepSeek to keep ownership of context, reasoning, task breakdown, decisions, testing judgment, and reporting while Mimo performs concrete execution tasks.

Tools

• mimo_vision: inspect an image or screenshot and return observable visual facts.
• mimo_visual_review: review a screenshot against expected behavior and report concrete visual issues.
• mimo_patch: produce a unified diff for a focused coding subtask.
• mimo_execute_task: token-saving autonomous execution loop for coding/build/test/git/script work.
• mimo_run_command: run terminal commands, scripts, tests, and git actions after the controller has chosen the exact action.

No general reasoning or second-opinion text tool is exposed. The controller should think first, then call Mimo with a concrete execution brief.

Important naming note:

• mimo-executor-zl-mcp is the npm package and executable command.
• mimo is the recommended MCP server name in clients.
• The callable tool names are mimo_vision, mimo_visual_review, mimo_patch, mimo_execute_task, and mimo_run_command.
• Some clients prefix tools with the server name. In Reasonix, these may appear as mimo_mimo_vision, mimo_mimo_visual_review, mimo_mimo_patch, mimo_mimo_execute_task, and mimo_mimo_run_command.
• Do not try to call mimo-executor-zl-mcp as a tool name.

Requirements

• Node.js 20 or newer.
• An OpenAI-compatible /chat/completions endpoint or Anthropic-compatible /v1/messages endpoint.
• A Mimo-compatible text model route.
• A multimodal model route for image tools.

Install

From npm, after publishing:

npm install -g mimo-executor-zl-mcp

From source:

git clone <your-repo-url>
cd mimo-executor-zl-mcp
cp .env.example .env
npm run check

Edit .env for your model gateway:

MIMO_API_FORMAT=anthropic
MIMO_BASE_URL=http://127.0.0.1:15721
MIMO_MESSAGES_PATH=/v1/messages
MIMO_MODEL=claude-opus-4-8
MIMO_TEXT_MODEL=claude-opus-4-8
MIMO_VISION_MODEL=claude-sonnet-4-6

If your gateway needs an explicit key:

MIMO_API_KEY=your_key_here

When MIMO_API_KEY is omitted, the server can read the active CCSwitch inferenceGatewayApiKey from Claude-3p/configLibrary on macOS.

Claude Code

Installed package:

claude mcp add-json -s user mimo '{"type":"stdio","command":"mimo-executor-zl-mcp","args":[]}'

Source checkout:

./install-claude-mcp.sh

The installer uses the script directory as the MCP server path and the current directory as the default workspace. Override the workspace with:

MIMO_WORKSPACE_DIR=/path/to/workspace ./install-claude-mcp.sh

Claude Desktop Or Reasonix

Installed package:

{
  "mcpServers": {
    "mimo": {
      "type": "stdio",
      "command": "mimo-executor-zl-mcp",
      "args": [],
      "env": {}
    }
  }
}

Source checkout:

{
  "mcpServers": {
    "mimo": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mimo-executor-zl-mcp/server.mjs"],
      "env": {}
    }
  }
}

Security

This server can read local files for context/images and can execute local commands through mimo_run_command. Only enable it for trusted controller models and trusted workspaces.

Recommended safety settings:

MIMO_WORKSPACE_ROOT=/path/to/trusted/workspace
MIMO_ALLOWED_COMMANDS=git,node,npm,pnpm,bun,bash
MIMO_ALLOW_SHELL=false
MIMO_COMMAND_TIMEOUT_MS=120000
MIMO_MAX_COMMAND_OUTPUT_BYTES=120000
MIMO_EXECUTION_MAX_STEPS=4
MIMO_EXECUTION_COMMAND_OUTPUT_BYTES=12000
MIMO_EXECUTION_SUMMARY_BYTES=4000

MIMO_WORKSPACE_ROOT restricts file reads and command working directories to one trusted tree. MIMO_ALLOWED_COMMANDS restricts command execution by executable name. Shell execution is disabled by default and requires MIMO_ALLOW_SHELL=true.

Operating Rule

Use Mimo as a controlled executor, not as the thinker or owner of the workspace.

When the Mimo tools are available, coding, file-edit execution, scripts, tests, git, build commands, image recognition, and visual review should be routed through the Mimo tools. The controller model should keep reasoning and final decisions.

For maximum controller-token savings, prefer mimo_execute_task over separate mimo_patch + mimo_run_command calls. mimo_execute_task keeps the noisy loop inside the MCP server:

Mimo reads focused files
  -> returns a patch
  -> MCP applies the patch
  -> MCP runs requested commands/tests
  -> command errors are sent back to Mimo compactly
  -> Mimo fixes again
  -> controller receives only compact summary/evidence

This prevents long build logs and repeated compiler errors from being copied into the controller model context.

For image tasks:

1. The controller saves or locates the image path.
2. The controller calls mimo_vision or mimo_visual_review.
3. The controller uses the returned visual facts to decide the next step.

For coding tasks:

1. The controller decides the task, constraints, key files, and acceptance checks.
2. The controller calls mimo_execute_task first.
3. Mimo performs the patch/test/fix loop internally.
4. The controller reviews the compact summary, changed files, and final status.
5. Use mimo_patch only for a single patch without an execution loop.

For terminal, script, test, and git tasks:

1. The controller decides the exact command, arguments, cwd, and timeout.
2. The controller calls mimo_run_command.
3. The controller inspects exit_code, stdout, stderr, and timed_out.
4. The controller decides the next step.

Environment

| Variable | Default | Purpose | | --- | --- | --- | | MIMO_API_FORMAT | openai | openai or anthropic. | | MIMO_BASE_URL | empty | Gateway base URL. | | MIMO_CHAT_COMPLETIONS_PATH | /chat/completions | OpenAI-compatible path. | | MIMO_MESSAGES_PATH | /v1/messages | Anthropic-compatible path. | | MIMO_API_KEY | empty | Explicit API key. | | MIMO_MODEL | mimo-2.5 | Fallback model. | | MIMO_TEXT_MODEL | MIMO_MODEL | Text/patch model. | | MIMO_VISION_MODEL | MIMO_MODEL | Vision model. | | MIMO_MAX_TOKENS | 4096 | Anthropic max tokens. | | MIMO_MAX_FILE_BYTES | 120000 | Max text file read size. | | MIMO_MAX_IMAGE_BYTES | 10000000 | Max image read size. | | MIMO_WORKSPACE_ROOT | empty | Optional trusted root for file reads and command cwd. | | MIMO_ALLOWED_COMMANDS | empty | Optional comma-separated command allowlist. | | MIMO_ALLOW_SHELL | false | Enable shell: true command execution. | | MIMO_COMMAND_TIMEOUT_MS | 120000 | Default command timeout. | | MIMO_MAX_COMMAND_OUTPUT_BYTES | 120000 | Combined output retention limit. | | MIMO_EXECUTION_MAX_STEPS | 4 | Default max internal repair iterations for mimo_execute_task. | | MIMO_EXECUTION_COMMAND_OUTPUT_BYTES | 12000 | Internal per-command output cap sent back to Mimo during execution loops. | | MIMO_EXECUTION_SUMMARY_BYTES | 4000 | Final summary cap returned to the controller. |

Smoke Test

npm run check
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n' | node server.mjs
npm pack --dry-run

The package should not include .env, local test images, API keys, or machine-specific config files.