Zen

Zen MCP enables you to orchestrate multiple AI models as a cohesive development team. You drive the prompts and workflows, while Claude coordinates model selection, cross-model reasoning, and tool usage to analyze, review, debug, refactor, and validate code across complex tasks. This server-centric approach lets you scale expert AI input, maintain context across steps, and apply specialized models to each subtasks for faster, higher-quality outcomes.

How to use

You interact with the Zen MCP Server through an MCP client. Create prompts that describe the task and the desired workflow, and Claude will route subtasks to the most appropriate models and tools. Use workflows like codereview for secure code audits, planner for breaking down large changes, precommit for validation, and analyze for architectural understanding. You can also request multi-model perspectives with consensus or debate ideas across providers to reach a well-rounded decision.

How to install

Prerequisites: ensure Python 3.10+ (3.12 recommended). Install uv to enable the quick startup workflow.

{
  "mcpServers": {
    "zen": {
      "command": "sh",
      "args": [
        "-c",
        "exec $(which uvx || echo uvx) --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server"
      ],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin",
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Add Your API Keys and Start Using It

Add API keys and environment configuration so Claude can access the models you plan to use. You can place keys in a .env file or export them in your shell environment. For example, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, and DIAL_API_KEY may be used depending on which providers you enable.

To apply the configuration, place the runtime command into your client configuration and start a new session of Claude Code CLI or Claude Desktop, then prompt Claude to begin working with zen.

Configuration and security notes

Zen MCP Server is designed for multi-model collaboration with controlled model usage. You can set DEFAULT_MODEL to auto or specify a preferred model per task. Environment variables control API keys, model access, and memory/timeout settings. Use a single, unified mcpServers entry for the Zen server in your client configuration.

Keep keys secure and avoid exposing them in public repositories. Use separate keys for OpenAI, Gemini, OpenRouter, DIAL, or local endpoints, and restrict model usage to prevent unintended costs.

Troubleshooting and tips

If you encounter issues, verify that the stdio command is running and that the environment variables are correctly set. Restart your MCP client session after making environment changes, as the server reads the .env values when Claude calls a tool.

When you need to test a new workflow, craft prompts that explicitly request specific models for certain tasks (for example, ask Gemini Pro to perform a codereview while O3 handles debugging) to maximize each model’s strengths.

Examples of practical usage

• Think deeper about a system design and have the best model reason through it with you using thinkdeep. - Run a codereview and then follow up with a precommit check to ensure changes meet your criteria. - Analyze a codebase, then plan a refactor using planner, and execute the changes in a structured, stepwise fashion.

Advanced prompts and tools

Use tool prompts to drive specialized workflows, such as /zen:planner to break down projects, /zen:consensus to gather multi-model opinions, or /zen:codereview to audit code. You can chain tools in a single conversation to achieve complex outcomes without losing context.

Available tools

chat

Collaborative thinking and development conversations to brainstorm ideas and validate approaches.

thinkdeep

Extended reasoning tool that challenges assumptions and explores edge cases with specialized thinking models.

challenge

Critical prompt that prompts the system to re-evaluate assumptions and avoid premature conclusions.

planner

Interactive planning to break down complex projects into manageable steps with sub-tasks.

consensus

Multi-model consensus analysis to gather diverse expert opinions and reach informed decisions.

codereview

Professional code review workflow with structured analysis and actionable feedback.

precommit

Pre-commit validation workflow that analyzes changes before they are committed.

debug

Systematic debugging assistant guiding root-cause analysis and fixes.

analyze

Smart analysis of code structure, dependencies, and patterns.

refactor

Intelligent refactoring guidance with decomposition and modernization focus.

tracer

Call-flow and dependency tracing for precise analyses.

testgen

Generation of comprehensive tests and edge-case coverage.

secaudit

Security audit with OWASP-based analysis and compliance checks.

docgen

Documentation generation with complexity analysis and gotchas.

listmodels

Displays all available AI models by provider and capabilities.

version

Server version and configuration details for diagnostics.