mcp-zen

Zen MCP Server provides Claude Desktop with streamlined access to multiple AI models via an NPX wrapper. When you run npx zen-mcp-server-199bio, the wrapper spins up the Zen MCP Server locally, making available several tools that integrate with Claude Desktop. After configuring API keys, Claude can access a suite of tools that enable rapid development tasks, including collaborative reasoning, code analysis, and debugging. The available tools are zen (default quick chat), chat (collaborative development discussions), thinkdeep (extended reasoning leveraging Gemini 2.0 Pro), codereview (professional code review), precommit (pre-commit validation), debug (advanced debugging assistance), and analyze (smart file and codebase analysis). Once configured, you can invoke these tools from Claude Desktop or via the Claude CLI to interact with the models through the Zen MCP Server. The wrapper handles automatic setup, virtual environments, and cross-model access, so you can focus on your development tasks rather than infrastructure. Quick usage involves launching the server with the NPX command and then selecting the desired tool in Claude to begin a session or conversation.

To use the tools efficiently, start by adding the zen tool (or any of the others) to Claude Desktop via the provided mcpServers entry and ensure your API keys are configured in the environment. Then, open Claude and select the Zen MCP Server tool alias (zen, chat, thinkdeep, codereview, precommit, debug, analyze) as needed for your workflow. For example, thinkdeep can be used for deep reasoning on complex design decisions, codereview can provide structured code feedback, and analyze can scan large codebases for hotspots and architecture patterns. If you need quick AI consultations, use zen as your default tool for fast, broad questions.

Prerequisites:

• Python 3.11+
• Node.js (for the NPX wrapper): Node.js v14+ installed
• Git
• At least one API key (Gemini, OpenAI, or OpenRouter)

Step-by-step installation:

1. Ensure Python and Node.js are installed. Verify versions:
   • python3 --version
   • node -v
2. Install or upgrade NPX-enabled wrapper by running:
   • npx zen-mcp-server-199bio This will fetch the Zen MCP Server wrapper and start the setup process.
3. First-time setup (auto-handled by the wrapper):
   • Checks Python 3.11+
   • Clones Zen MCP Server to ~/.zen-mcp-server
   • Creates a .env file and prompts for API keys
   • Creates and activates a Python virtual environment
   • Installs dependencies automatically
4. Prepare API keys in environment variables (example):
   • GEMINI_API_KEY=your_gemini_key_here
   • OPENAI_API_KEY=your_openai_key_here
   • OPENROUTER_API_KEY=your_openrouter_key_here
5. Ensure Claude Desktop is configured to connect to the MCP server using the provided mcpServers entry. Restart Claude Desktop after configuration.

If you prefer to run manually without the wrapper: you can still configure and run the Zen MCP Server locally by cloning the Zen MCP Server repo to ~/.zen-mcp-server, creating and activating a venv, and installing dependencies from requirements.txt, then running the server script directly. This path, however, is not the recommended flow provided by the NPX wrapper.

Tips and caveats:

• No Docker is required; the server runs directly with Python, offering faster startup and lower overhead.
• Keep at least one API key configured; OpenRouter keys enable access to many models via a single interface.
• If you encounter dependency issues, you can manually recreate the environment inside ~/.zen-mcp-server by creating a virtual environment and reinstalling requirements.txt as a fallback.
• For Claude Desktop, ensure the claude_desktop_config.json includes the zen entry and that the environment variables (API keys) are correctly set.
• If you update API keys, remember to restart Claude Desktop or re-load the MCP server configuration to pick up new credentials.
• The Zen MCP Server supports multi-model access and conversation threading, but API usage limits and model availability depend on your API provider accounts.