zen-mcp-server

# Zen MCP: Many Workflows. One Context.

[![zen_web.webm](https://github.com/user-attachments/assets/851e3911-7f06-47c0-a4ab-a2601236697c)](https://github.com/user-attachments/assets/851e3911-7f06-47c0-a4ab-a2601236697c)

<div align="center">
  <b>🤖 <a href="https://www.anthropic.com/claude-code">Claude</a> OR <a href="https://github.com/google-gemini/gemini-cli">Gemini CLI</a> + [Gemini / OpenAI / Grok / OpenRouter / DIAL / Ollama / Any Model] = Your Ultimate AI Development Team</b>
</div>

<br/>

Zen MCP is a Model Context Protocol (MCP) server designed to enhance your coding agent (Claude or Gemini CLI) with access to multiple AI models. It facilitates advanced code analysis, problem-solving, and collaborative development by enabling seamless context sharing across different AI models and workflows.

**Key Features:**

*   **True AI Orchestration:** Conversations seamlessly continue across workflows. Give Claude a complex task, and it will automatically orchestrate between models, leveraging the best AI for each subtask.
*   **Workflow-Driven Development:** Integrates with tools like `planner`, `analyze`, `codereview`, `refactor`, `debug`, and `precommit` to provide structured, developer-centric processes.
*   **Multi-Model Perspectives:** Claude can switch between different tools and models mid-conversation, with context carrying forward seamlessly.
*   **Context Revival:** Even after Claude's context resets, the MCP server retains conversation history, allowing other models to revive Claude's understanding without re-ingesting lengthy documents or code.

**Example Workflow - Claude Code:**

1.  `Perform a codereview using gemini pro and o3 and use planner to generate a detailed plan, implement the fixes and do a final precommit check by continuing from the previous codereview`
2.  This triggers a `codereview` workflow where Claude examines the code, looking for issues.
3.  Claude collects relevant code and notes issues, tracking confidence levels (`exploring`, `low`, `medium`, `high`, `certain`).
4.  A detailed list of critical to low issues is generated.
5.  Relevant files and findings are shared with **Gemini Pro** for a second `codereview`.
6.  The process repeats with O3, adding new discoveries to the prompt.
7.  Claude combines all feedback into a single list of critical to low issues, including good patterns.
8.  The `planner` workflow breaks down major refactors into simpler steps.
9.  Claude performs the actual work of fixing highlighted issues.
10. Claude returns to Gemini Pro for a `precommit` review.

All within a single conversation thread! Gemini Pro in step 11 *knows* what was recommended by O3 in step 7, taking that context into consideration for its final pre-commit review.

**Zen MCP: Super-Glue for Your AI Development Team**

> **Remember:** Claude stays in full control — but **YOU** call the shots.
> Zen is designed to have Claude engage other models only when needed — and to follow through with meaningful back-and-forth.
> **You're** the one who crafts the powerful prompt that makes Claude bring in Gemini, Flash, O3 — or fly solo.
> You're the guide. The prompter. The puppeteer.
> ### You are the AI - **Actually Intelligent**.

Because these AI models [clearly aren't when they get chatty →](docs/ai_banter.md)

## Table of Contents

- [Why This Server?](#why-this-server)
- [Quick Navigation](#quick-navigation)
- [Pro Tip: Context Revival](#pro-tip-context-revival)
- [Quickstart (5 minutes)](#quickstart-5-minutes)
  - [Prerequisites](#prerequisites)
  - [1. Get API Keys](#1-get-api-keys)
  - [2. Choose Your Installation Method](#2-choose-your-installation-method)
  - [3. Add Your API Keys](#3-add-your-api-keys)
  - [4. Start Using It!](#4-start-using-it)
- [Available Tools](#available-tools)
  - [1. `chat` - General Development Chat & Collaborative Thinking](#1-chat---general-development-chat--collaborative-thinking)
  - [2. `thinkdeep` - Extended Reasoning Partner](#2-thinkdeep---extended-reasoning-partner)
  - [3. `challenge` - Critical Challenge Prompt](#3-challenge---critical-challenge-prompt)
  - [4. `planner` - Interactive Step-by-Step Planning](#4-planner---interactive-step-by-step-planning)
  - [5. `consensus` - Multi-Model Perspective Gathering](#5-consensus---multi-model-perspective-gathering)
  - [6. `codereview` - Professional Code Review](#6-codereview---professional-code-review)
  - [7. `precommit` - Pre-Commit Validation](#7-precommit---pre-commit-validation)
  - [8. `debug` - Expert Debugging Assistant](#8-debug---expert-debugging-assistant)
  - [9. `analyze` - Smart File Analysis](#9-analyze---smart-file-analysis)
  - [10. `refactor` - Intelligent Code Refactoring](#10-refactor---intelligent-code-refactoring)
  - [11. `tracer` - Static Code Analysis Prompt Generator](#11-tracer---static-code-analysis-prompt-generator)
  - [12. `testgen` - Comprehensive Test Generation](#12-testgen---comprehensive-test-generation)
  - [13. `secaudit` - Comprehensive Security Audit](#13-secaudit---comprehensive-security-audit)
  - [14. `docgen` - Comprehensive Documentation Generation](#14-docgen---comprehensive-documentation-generation)
  - [15. `listmodels` - List Available Models](#15-listmodels---list-available-models)
  - [16. `version` - Server Information](#16-version---server-information)
  - [Prompt Support](#prompt-support)
- [Advanced Features](#advanced-features)
  - [AI-to-AI Conversation Threading](#ai-to-ai-conversation-threading)
- [Configuration](#configuration)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Star History](#star-history)

## Why This Server?

Zen MCP addresses common limitations when working with coding agents like Claude:

*   **Guided Workflows:** Enforces systematic investigation, preventing rushed analysis by ensuring thorough code examination at each phase. (`debug`, `precommit`, `refactor`, `analyze`, `codereview`)
*   **Multiple AI Perspectives:** Orchestrates between different models to get the best analysis.
*   **Automatic Model Selection:** Claude picks the right model for each task (or you can specify).
*   **Senior Developer Partner:** Validates and extends ideas. (`chat`)
*   **Second Opinion:** Augments Claude's thinking with perspectives from Gemini Pro, O3, or other models via custom endpoints. (`thinkdeep`)
*   **Multiple Expert Opinions:** Different AI models debate ideas to help you make better decisions. (`consensus`)
*   **Professional Code Reviews:** Actionable feedback across entire repositories. (`codereview`)
*   **Pre-Commit Validation:** Deep analysis using the best model for the job. (`precommit`)
*   **Expert Debugging:** O3 for logical issues, Gemini for architectural problems. (`debug`)
*   **Extended Context Windows:** Delegates analysis to Gemini (1M tokens) or O3 (200K tokens) for entire codebases, large datasets, or comprehensive documentation.
*   **Model-Specific Strengths:** Extended thinking with Gemini Pro, fast iteration with Flash, strong reasoning with O3, local privacy with Ollama.
*   **Local Model Support:** Run models like Llama 3.2 locally via Ollama, vLLM, or LM Studio for privacy and cost control.
*   **Dynamic Collaboration:** Models can request additional context and follow-up replies from Claude mid-analysis.
*   **Smart File Handling:** Automatically expands directories, manages token limits based on model capacity.
*   **Vision Support:** Analyze images, diagrams, screenshots, and visual content with vision-capable models.
*   **[Bypass MCP's token limits](docs/advanced-usage.md#working-with-large-prompts)**: Work around MCP's 25K limit automatically.
*   **[Context revival across sessions](docs/context-revival.md)**: Continue conversations even after Claude's context resets, with other models maintaining full history.

## Quick Navigation