{"type":"mcp_server","name":"zen-mcp-server","description":"**Option 1 (Focus on Model Orchestration):**\n\n> Model Context Protocol server. Orchestrates Claude + other LLMs (Gemini, OpenAI, etc.) for combined processing.\n\n**Option 2 (Focus on Unified Interface)","category":"AI","language":"Python","stars":11625,"forks":370,"owner":"BeehiveInnovations","github_url":"https://github.com/BeehiveInnovations/zen-mcp-server","homepage":null,"setup":"## Setup\n\n### Prerequisites\n\n- Python 3.10+ (3.12 recommended)\n- Git\n- **Windows users**: WSL2 is required for Claude Code CLI\n\n### 1. Get API Keys (at least one required)\n\n**Option A: OpenRouter (Access multiple models with one API)**\n- **OpenRouter**: Visit [OpenRouter](https://openrouter.ai/) for access to multiple models through one API. [Setup Guide](docs/custom_models.md)\n  - Control model access and spending limits directly in your OpenRouter dashboard\n  - Configure model aliases in [`conf/custom_models.json`](conf/custom_models.json)\n\n**Option B: Native APIs**\n- **Gemini**: Visit [Google AI Studio](https://makersuite.google.com/app/apikey) and generate an API key. For best results with Gemini 2.5 Pro, use a paid API key as the free tier has limited access to the latest models.\n- **OpenAI**: Visit [OpenAI Platform](https://platform.openai.com/api-keys) to get an API key for O3 model access.\n- **X.AI**: Visit [X.AI Console](https://console.x.ai/) to get an API key for GROK model access.\n- **DIAL**: Visit [DIAL Platform](https://dialx.ai/) to get an API key for accessing multiple models through their unified API. DIAL is an open-source AI orchestration platform that provides vendor-agnostic access to models from major providers, open-source community, and self-hosted deployments. [API Documentation](https://dialx.ai/dial_api)\n\n**Option C: Custom API Endpoints (Local models like Ollama, vLLM)**\n[Please see the setup guide](docs/custom_models.md#option-2-custom-api-setup-ollama-vllm-etc). With a custom API you can use:\n- **Ollama**: Run models like Llama 3.2 locally for free inference\n- **vLLM**: Self-hosted inference server for high-throughput inference\n- **LM Studio**: Local model hosting with OpenAI-compatible API interface\n- **Text Generation WebUI**: Popular local interface for running models\n- **Any OpenAI-compatible API**: Custom endpoints for your own infrastructure\n\n> **Note:** Using multiple provider options may create ambiguity about which provider / model to use if there is an overlap.\n> If all APIs are configured, native APIs will take priority when there is a clash in model name, such as for `gemini` and `o3`.\n> Configure your model aliases and give them unique names in [`conf/custom_models.json`](conf/custom_models.json)\n\n### 2. Choose Your Installation Method\n\n**Option A: Quick Install with uvx**\n\n**Prerequisites**: Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first (required for uvx)\n\n<details>\n<summary>Claude Desktop Configuration</summary>\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zen\": {\n      \"command\": \"sh\",\n      \"args\": [\n        \"-c\",\n        \"exec $(which uvx || echo uvx) --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server\"\n      ],\n      \"env\": {\n        \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n        \"OPENAI_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Claude Code CLI Configuration</summary>\n\nCreate a `.mcp.json` file in your project root for [project-scoped configuration](https://docs.anthropic.com/en/docs/claude-code/mcp#project-scope):\n\n```json\n{\n  \"mcpServers\": {\n    \"zen\": {\n      \"command\": \"sh\",\n      \"args\": [\n        \"-c\",\n        \"exec $(which uvx || echo uvx) --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server\"\n      ],\n      \"env\": {\n        \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n        \"OPENAI_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Gemini CLI Configuration</summary>\n\nEdit `~/.gemini/settings.json` and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"zen\": {\n      \"command\": \"sh\",\n      \"args\": [\n        \"-c\",\n        \"exec $(which uvx || echo uvx) --from git+https://github.com/BeehiveInnovations/zen-mcp-server.git zen-mcp-server\"\n      ],\n      \"env\": {\n        \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n        \"OPENAI_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Note**: While Zen MCP Server connects successfully to Gemini CLI, tool invocation is not working correctly yet. See [Gemini CLI Setup](docs/gemini-setup.md) for updates.\n</details>\n\n**What this does:**\n- **Zero setup required** - uvx handles everything automatically\n- **Always up-to-date** - Pulls latest version on each run\n- **No local dependencies** - Works without Python environment setup\n- **Instant availability** - Ready to use immediately\n\n**Option B: Traditional Clone and Set Up**\n\n```bash\n# Clone the repository\ngit clone https://github.com/BeehiveInnovations/zen-mcp-server.git\ncd zen-mcp-server\n\n# One-command setup installs Zen in Claude\n./run-server.sh\n\n# Or for Windows users using PowerShell:\n./run-server.ps1\n\n# To view MCP configuration for Claude\n./run-server.sh -c\n\n# PowerShell:\n./run-server.ps1 -Config\n\n# See help for more\n./run-server.sh --help\n\n# PowerShell:\n./run-server.ps1 -Help\n```\n\n**What this does:**\n- **Sets up everything automatically** - Python environment, dependencies, configuration\n- **Configures Claude integrations** - Adds to Claude Code CLI and guides Desktop setup\n- **Ready to use immediately** - No manual configuration needed\n- **Also works with Gemini CLI** - See [Gemini CLI Setup](docs/gemini-setup.md) for configuration\n\n**After updates:** Always run `./run-server.sh` again after `git pull` to ensure everything stays current.\n\n**Windows users:** Using WSL? See the [WSL Setup Guide](docs/wsl-setup.md) for detailed instructions.\n\n### 3. Add Your API Keys\n\nCreate a `.env` file in the root directory of the project and add your API keys:\n\n```bash\n# Edit .env to add your API keys (if not already set in environment)\nnano .env\n```\n\nThe `.env` file should contain at least one of the following:\n\n```\nGEMINI_API_KEY=your-gemini-api-key-here  # For Gemini models\nOPENAI_API_KEY=your-openai-api-key-here  # For O3 model\nOPENROUTER_API_KEY=your-openrouter-key  # For OpenRouter (see docs/custom_models.md)\nDIAL_API_KEY=your-dial-api-key-here      # For DIAL platform\n\n# For DIAL (optional configuration):\nDIAL_API_HOST=https://core.dialx.ai      # Default DIAL host (optional)\nDIAL_API_VERSION=2024-12-01-preview      # API version (optional)\nDIAL_ALLOWED_MODELS=o3,gemini-2.5-pro    # Restrict to specific models (optional)\n\n# For local models (Ollama, vLLM, etc.):\nCUSTOM_API_URL=http://localhost:11434/v1  # Ollama example\nCUSTOM_API_KEY=                                      # Empty for Ollama\nCUSTOM_MODEL_NAME=llama3.2                          # Default model\n\n# Note: At least one API key OR custom URL is required\n```\n\n**No restart needed**: The server reads the .env file each time Claude calls a tool, so changes take effect immediately.\n\n**Next**: Now run `claude` from your project folder using the terminal for it to connect to the newly added mcp server.\nIf you were already running a `claude` code session, please exit and start a new session.\n\n#### If Setting up for Claude Desktop","tools":"## Available Tools\n\nThese aren't just tools—they're how you get Claude to think like a real developer. Instead of rushing to reply with surface-level takes or shallow-insight, these workflows make Claude pause, dig into your code, and reason through problems step by step.\n\nIt's the difference between a rushed guess and a focused second pair of eyes that actually understands your code. Try them and feel the difference.\n\n**Quick Tool Selection Guide:**\n- **Need a thinking partner?** → `chat` (brainstorm ideas, get second opinions, validate approaches)\n- **Need deeper thinking?** → `thinkdeep` (extends analysis, finds edge cases)\n- **Want to prevent \"You're absolutely right!\" responses?** → `challenge` (challenges assumptions, encourages thoughtful re-evaluation)\n- **Need to break down complex projects?** → `planner` (step-by-step planning, project structure, breaking down complex ideas)\n- **Need multiple perspectives?** → `consensus` (get diverse expert opinions on proposals and decisions)\n- **Code needs review?** → `codereview` (bugs, security, performance issues)\n- **Pre-commit validation?** → `precommit` (validate git changes before committing)\n- **Something's broken?** → `debug` (systematic investigation, step-by-step root cause analysis)\n- **Want to understand code?** → `analyze` (architecture, patterns, dependencies)\n- **Code needs refactoring?** → `refactor` (intelligent refactoring with decomposition focus)\n- **Need call-flow analysis?** → `tracer` (generates prompts for execution tracing and dependency mapping)\n- **Need comprehensive tests?** → `testgen` (generates test suites with edge cases)\n- **Security concerns?** → `secaudit` (OWASP analysis, compliance evaluation, vulnerability assessment)\n- **Code needs documentation?** → `docgen` (generates comprehensive documentation with complexity analysis)\n- **Which models are available?** → `listmodels` (shows all configured providers and models)\n- **Server info?** → `version` (version and configuration details)\n\n**Auto Mode:** When `DEFAULT_MODEL=auto`, Claude automatically picks the best model for each task. You can override with: \"Use flash for quick analysis\" or \"Use o3 to debug this\".\n\n**Model Selection Examples:**\n- Complex architecture review → Claude picks Gemini Pro\n- Quick formatting check → Claude picks Flash\n- Logical debugging → Claude picks O3\n- General explanations → Claude picks Flash for speed\n- Local analysis → Claude picks your Ollama model\n\n**Pro Tip:** Thinking modes (for Gemini models) control depth vs token cost. Use \"minimal\" or \"low\" for quick tasks, \"high\" or \"max\" for complex problems. [Learn more](docs/advanced-usage.md#thinking-modes)\n\n**Tools Overview:**\n1. [`chat`](docs/tools/chat.md) - Collaborative thinking and development conversations\n2. [`thinkdeep`](docs/tools/thinkdeep.md) - Extended reasoning and problem-solving\n3. [`challenge`](docs/tools/challenge.md) - Critical challenge prompt, prevents **You're absolutely right!**\n4. [`planner`](docs/tools/planner.md) - Interactive sequential planning for complex projects\n5. [`consensus`](docs/tools/consensus.md) - Multi-model consensus analysis with stance steering\n6. [`codereview`](docs/tools/codereview.md) - Professional code review with severity levels\n7. [`precommit`](docs/tools/precommit.md) - Validate git changes before committing\n8. [`debug`](docs/tools/debug.md) - Systematic investigation and debugging\n9. [`analyze`](docs/tools/analyze.md) - General-purpose file and code analysis\n10. [`refactor`](docs/tools/refactor.md) - Code refactoring with decomposition focus\n11. [`tracer`](docs/tools/tracer.md) - Static code analysis prompt generator for call-flow mapping\n12. [`testgen`](docs/tools/testgen.md) - Comprehensive test generation with edge case coverage\n13. [`secaudit`](docs/tools/secaudit.md) - Comprehensive security audit with OWASP Top 10 analysis\n14. [`docgen`](docs/tools/docgen.md) - Comprehensive documentation generation with complexity analysis\n15. [`listmodels`](docs/tools/listmodels.md) - Display all available AI models organized by provider\n16. [`version`](docs/tools/version.md) - Get server version and configuration\n\n### 1. `chat` - General Development Chat & Collaborative Thinking\nYour thinking partner for brainstorming, getting second opinions, and validating approaches. Perfect for technology comparisons, architecture discussions, and collaborative problem-solving.\n\n```\nChat with zen about the best approach for user authentication in my React app\n```\n\n**[📖 Read More](docs/tools/chat.md)** - Detailed features, examples, and best practices\n\n### 2. `thinkdeep` - Extended Reasoning Partner\nGet a second opinion to augment Claude's own extended thinking. Uses specialized thinking models to challenge assumptions, identify edge cases, and provide alternative perspectives.\n\n```\nThe button won't animate when clicked, it seems something else is intercepting the clicks. Use thinkdeep with gemini pro after gathering related code and handing it the files\nand find out what the root cause is\n```\n\n**[📖 Read More](docs/tools/thinkdeep.md)** - Enhanced analysis capabilities and critical evaluation process\n\n### 3. `challenge` - Critical Challenge Prompt\nEncourages thoughtful reassessment of statements instead of automatic agreement, especially when you're wrong.\nWraps your input with instructions for critical thinking and honest analysis.\n\n```\nchallenge isn't adding this function to the base class a bad idea?\n```\n\n**[📖 Read More](docs/tools/challenge.md)** - Challenge an approach or validate ideas with confidence\n\n### 4. `planner` - Interactive Step-by-Step Planning\nBreak down complex projects or ideas into manageable, structured plans through step-by-step thinking.\nPerfect for adding new features to an existing system, scaling up system design, migration strategies,\nand architectural planning with branching and revision capabilities.\n\n```\nCreate two separate sub-tasks: in one, using planner tool show me how to add natural language support\nto my cooking app. In the other sub-task, use planner to plan how to add support for voice notes to my cooking app.\nOnce done, start a consensus by sharing both plans to o3 and flash to give me the final verdict. Which one do\nI implement first?\n```\n\n**[📖 Read More](docs/tools/planner.md)** - Step-by-step planning methodology and multi-session continuation\n\n### 5. `consensus` - Multi-Model Perspective Gathering\nGet diverse expert opinions from multiple AI models on technical proposals and decisions. Supports stance steering (for/against/neutral) and structured decision-making.\n\n```\nGet a consensus with flash taking a supportive stance and gemini pro being critical to evaluate whether we should\nmigrate from REST to GraphQL for our API. I need a definitive answer.\n```\n\n**[📖 Read More](docs/tools/consensus.md)** - Multi-model orchestration and decision analysis\n\n### 6. `codereview` - Professional Code Review\nComprehensive code analysis with prioritized feedback and severity levels. This workflow tool guides Claude through systematic investigation steps with forced pauses between each step to ensure thorough code examination, issue identification, and quality assessment before providing expert analysis.\n\n```\nPerform a codereview with gemini pro especially the auth.py as I feel some of the code is bypassing security checks\nand there may be more potential vulnerabilities. Find and share related code.\"\n```\n\n**[📖 Read More](docs/tools/codereview.md)** - Professional review workflow with step-by-step analysis\n\n### 7. `precommit` - Pre-Commit Validation\nComprehensive review of staged/unstaged git changes across multiple repositories. This workflow tool guides Claude through systematic investigation of git changes, repository status, and file modifications across multiple steps before providing expert validation to ensure changes meet requirements and prevent regressions.\n\n```\nPerform a thorough precommit with o3, we want to only highlight critical issues, no blockers, no regressions. I need\n100% confidence this covers all the edge cases listed in FIX_ISSUE_ABC.md\n```\n\n**[📖 Read More](docs/tools/precommit.md)** - Multi-repository validation and change analysis\n\n### 8. `debug` - Expert Debugging Assistant\nSystematic investigation-guided debugging that walks Claude through step-by-step root cause analysis. This workflow \ntool enforces a structured investigation process where Claude performs methodical code examination, evidence collection, \nand hypothesis formation across multiple steps before receiving expert analysis from the selected AI model.\n\n```\nSee logs under /Users/me/project/diagnostics.log and related code under the sync folder.\nLogs show that sync works but sometimes it gets stuck and there are no errors displayed to\nthe user. Using zen's debug tool with gemini pro, find out why this is happening and what the root\ncause is and its fix\n```\n\n**[📖 Read More](docs/tools/debug.md)** - Step-by-step investigation methodology with workflow enforcement\n\n### 9. `analyze` - Smart File Analysis\nGeneral-purpose code","faq":null,"created_at":"2025-06-08T15:36:50+00:00","updated_at":"2025-07-07T16:32:30+00:00","source_url":"https://model-context-protocol.com/servers/zen-mcp-server","related_articles":[{"title":"Mastering zen-mcp-server in 2025","url":"https://model-context-protocol.com/blog/zen-mcp-server-guide"}]}