Zen MCP: Many Workflows. One Context.

zen_web.webm

AI orchestration for Claude Code - A Model Context Protocol server that gives your CLI of choice (e.g. Claude Code) access to multiple AI models for enhanced code analysis, problem-solving, and collaborative development. Zen works with Claude Code, Gemini CLI, Codex CLI as well as others.

True AI collaboration with conversation continuity - Claude stays in control but gets perspectives from the best AI for each subtask. Context carries forward seamlessly across tools and models, enabling complex workflows like: code reviews with multiple models → automated planning → implementation → pre-commit validation.

You're in control. Claude orchestrates the AI team, but you decide the workflow. Craft powerful prompts that bring in Gemini Pro, GPT 5, Flash, or local offline models exactly when needed.

Quick Start (5 minutes)

Prerequisites: Python 3.10+, Git, uv installed

1. Get API Keys (choose one or more):

• OpenRouter - Access multiple models with one API
• Gemini - Google's latest models
• OpenAI - O3, GPT-5 series
• X.AI - Grok models
• DIAL - Vendor-agnostic model access
• Ollama - Local models (free)

2. Install (choose one):

Option A: Clone and Automatic Setup (recommended)

git clone https://github.com/BeehiveInnovations/zen-mcp-server.git
cd zen-mcp-server

# Handles everything: setup, config, API keys from system environment. 
# Auto-configures Claude Desktop, Claude Code, Gemini CLI, Codex CLI
# Enable / disable additional settings in .env
./run-server.sh  

Option B: Instant Setup with uvx

// Add to ~/.claude/settings.json or .mcp.json
// Don't forget to add your API keys under env
{
  "mcpServers": {
    "zen": {
      "command": "bash",
      "args": ["-c", "for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \"$p\" ] && exec \"$p\" --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server; done; echo 'uvx not found' >&2; exit 1"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin",
        "GEMINI_API_KEY": "your-key-here",
        "DISABLED_TOOLS": "analyze,refactor,testgen,secaudit,docgen,tracer",
        "DEFAULT_MODEL": "auto"
      }
    }
  }
}

3. Start Using!

"Use zen to analyze this code for security issues with gemini pro"
"Debug this error with o3 and then get flash to suggest optimizations"
"Plan the migration strategy with zen, get consensus from multiple models"

👉 Complete Setup Guide with detailed installation, configuration for Gemini / Codex, and troubleshooting

Core Tools

Note: Each tool comes with its own multi-step workflow, parameters, and descriptions that consume valuable context window space even when not in use. To optimize performance, some tools are disabled by default. See Tool Configuration below to enable them.

Collaboration & Planning (Enabled by default)

• chat - Brainstorm ideas, get second opinions, validate approaches
• thinkdeep - Extended reasoning, edge case analysis, alternative perspectives
• planner - Break down complex projects into structured, actionable plans
• consensus - Get expert opinions from multiple AI models with stance steering

Code Analysis & Quality

• debug - Systematic investigation and root cause analysis
• precommit - Validate changes before committing, prevent regressions
• codereview - Professional reviews with severity levels and actionable feedback
• analyze (disabled by default - enable) - Understand architecture, patterns, dependencies across entire codebases

Development Tools (Disabled by default - enable)

• refactor - Intelligent code refactoring with decomposition focus
• testgen - Comprehensive test generation with edge cases
• secaudit - Security audits with OWASP Top 10 analysis
• docgen - Generate documentation with complexity analysis

Utilities

• challenge - Prevent "You're absolutely right!" responses with critical analysis
• tracer (disabled by default - enable) - Static analysis prompts for call-flow mapping

# Default configuration (from .env.example)
DISABLED_TOOLS=analyze,refactor,testgen,secaudit,docgen,tracer

# To enable specific tools, remove them from the list
# Example: Enable analyze tool
DISABLED_TOOLS=refactor,testgen,secaudit,docgen,tracer

# To enable ALL tools
DISABLED_TOOLS=

// In ~/.claude/settings.json or .mcp.json
{
  "mcpServers": {
    "zen": {
      "env": {
        // Tool configuration
        "DISABLED_TOOLS": "refactor,testgen,secaudit,docgen,tracer",
        "DEFAULT_MODEL": "pro",
        "DEFAULT_THINKING_MODE_THINKDEEP": "high",
        
        // API configuration
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key",
        "OPENROUTER_API_KEY": "your-openrouter-key",
        
        // Logging and performance
        "LOG_LEVEL": "INFO",
        "CONVERSATION_TIMEOUT_HOURS": "6",
        "MAX_CONVERSATION_TURNS": "50"
      }
    }
  }
}

// Remove or empty the DISABLED_TOOLS to enable everything
{
  "mcpServers": {
    "zen": {
      "env": {
        "DISABLED_TOOLS": ""
      }
    }
  }
}

Key Features

AI Orchestration

• Auto model selection - Claude picks the right AI for each task
• Multi-model workflows - Chain different models in single conversations
• Conversation continuity - Context preserved across tools and models
• Context revival - Continue conversations even after context resets

Model Support

• Multiple providers - Gemini, OpenAI, X.AI, OpenRouter, DIAL, Ollama
• Latest models - GPT-5, Gemini 2.5 Pro, O3, Grok-4, local Llama
• Thinking modes - Control reasoning depth vs cost
• Vision support - Analyze images, diagrams, screenshots

Developer Experience

• Guided workflows - Systematic investigation prevents rushed analysis
• Smart file handling - Auto-expand directories, manage token limits
• Web search integration - Access current documentation and best practices
• Large prompt support - Bypass MCP's 25K token limit

Example Workflows

Multi-model Code Review:

"Perform a codereview using gemini pro and o3, then use planner to create a fix strategy"

→ Claude reviews code systematically → Consults Gemini Pro → Gets O3's perspective → Creates unified action plan

Collaborative Debugging:

"Debug this race condition with max thinking mode, then validate the fix with precommit"

→ Deep investigation → Expert analysis → Solution implementation → Pre-commit validation

Architecture Planning:

"Plan our microservices migration, get consensus from pro and o3 on the approach"

→ Structured planning → Multiple expert opinions → Consensus building → Implementation roadmap

👉 Advanced Usage Guide for complex workflows, model configuration, and power-user features

Quick Links

📖 Documentation

• Getting Started - Complete setup guide
• Tools Reference - All tools with examples
• Advanced Usage - Power user features
• Configuration - Environment variables, restrictions

🔧 Setup & Support

• WSL Setup - Windows users
• Troubleshooting - Common issues
• Contributing - Code standards, PR process

License

Apache 2.0 License - see LICENSE file for details.

Acknowledgments

Built with the power of Multi-Model AI collaboration 🤝

• Actual Intelligence by real Humans
• MCP (Model Context Protocol) by Anthropic
• Claude Code - Your AI coding orchestrator
• Gemini 2.5 Pro & Flash - Extended thinking & fast analysis
• OpenAI O3 & GPT-5 - Strong reasoning & latest capabilities

Star History