BeehiveInnovations/zen-mcp-server

Zen MCP: Many Workflows. One Context.

🆕 Now with CLI-to-CLI Bridge

The new (CLI + Link) tool connects external AI CLIs directly into your workflow:

• Connect external CLIs like Gemini CLI, Codex CLI, and Claude Code directly into your workflow
• CLI Subagents - Launch isolated CLI instances from within your current CLI! Claude Code can spawn Codex subagents, Codex can spawn Gemini CLI subagents, etc. Offload heavy tasks (code reviews, bug hunting) to fresh contexts while your main session's context window remains unpolluted. Each subagent returns only final results.
• Context Isolation - Run separate investigations without polluting your primary workspace
• Role Specialization - Spawn planner, codereviewer, or custom role agents with specialized system prompts
• Full CLI Capabilities - Web search, file inspection, MCP tool access, latest documentation lookups
• Seamless Continuity - Sub-CLIs participate as first-class members with full conversation context between tools

# Codex spawns Codex subagent for isolated code review in fresh context
clink with codex codereviewer to audit auth module for security issues
# Subagent reviews in isolation, returns final report without cluttering your context as codex reads each file and walks the directory structure

# Consensus from different AI models → Implementation handoff with full context preservation between tools
Use consensus with gpt-5 and gemini-pro to decide: dark mode or offline support next
Continue with clink gemini - implement the recommended feature
# Gemini receives full debate context and starts coding immediately

👉

Why Zen MCP?

Why rely on one AI model when you can orchestrate them all?

A Model Context Protocol server that supercharges tools like Claude Code, Codex CLI, and IDE clients such as Cursor or the Claude Dev VS Code extension. Zen MCP connects your favorite AI tool to multiple AI models for enhanced code analysis, problem-solving, and collaborative development.

True AI Collaboration with Conversation Continuity

Zen supports conversation threading so your CLI can discuss ideas with multiple AI models, exchange reasoning, get second opinions, and even run collaborative debates between models to help you reach deeper insights and better solutions.

Your CLI always 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. Your CLI of choice 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.

Recommended AI Stack

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
• Azure OpenAI - Enterprise deployments of GPT-4o, GPT-4.1, GPT-5 family
• 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, Qwen 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"
"clink with cli_name=\"gemini\" role=\"planner\" to draft a phased rollout plan"

👉 with detailed installation, configuration for Gemini / Codex / Qwen, and troubleshooting 👉 for IDE integration instructions 📺 Watch tools in action to see real-world examples

Provider Configuration

Zen activates any provider that has credentials in your .env. See .env.example for deeper customization.

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)

• - Bridge requests to external AI CLIs (Gemini planner, codereviewer, etc.)
• - Brainstorm ideas, get second opinions, validate approaches. With capable models (GPT-5 Pro, Gemini 2.5 Pro), generates complete code / implementation
• - Extended reasoning, edge case analysis, alternative perspectives
• - Break down complex projects into structured, actionable plans
• - Get expert opinions from multiple AI models with stance steering

Code Analysis & Quality

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

Development Tools (Disabled by default - enable)

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

Utilities

• - Forces current-year API/SDK documentation lookups in a sub-process (saves tokens within the current context window), prevents outdated training data responses
• - Prevent "You're absolutely right!" responses with critical analysis
• (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": ""
      }
    }
  }
}

📺 Watch Tools In Action

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
• - Continue conversations even after context resets

Model Support

• Multiple providers - Gemini, OpenAI, Azure, X.AI, OpenRouter, DIAL, Ollama
• Latest models - GPT-5, Gemini 2.5 Pro, O3, Grok-4, local Llama
• - 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
• - 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

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

Quick Links

📖 Documentation

• - High-level map of major guides
• - Complete setup guide
• - All tools with examples
• - Power user features
• - Environment variables, restrictions
• - Provider-specific setup (OpenAI, Azure, custom gateways)
• - How intelligence scores drive auto-mode suggestions

🔧 Setup & Support

• - Windows users
• - Common issues
• - Code standards, PR process

License

Apache 2.0 License - see file for details.

Acknowledgments

Built with the power of Multi-Model AI collaboration 🤝

• Actual Intelligence by real Humans
• MCP (Model Context Protocol)
• Codex CLI
• Claude Code
• Gemini
• OpenAI
• Azure OpenAI

Star History