Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• requirements.txt
• run-server.sh
• run-server.ps1
• config.py
• README.md
• AGENTS.md
• systemprompts/generate_code_prompt.py

This guide provides instructions for setting up and running the Zen MCP (Model Context Protocol) server. The server acts as a bridge, connecting AI development tools like Claude Code, Codex CLI, and Cursor to a multitude of AI models from various providers. It enables multi-model orchestration, conversation continuity, and advanced development workflows, allowing a user's preferred CLI to leverage the strengths of different AI models within a single, continuous context.

The core functionality revolves around receiving requests from an MCP-compatible client, routing them to the appropriate AI model (or a workflow of models), and managing the conversation history to enable complex, multi-step tasks.

Sources: README.md

Prerequisites

Before you begin, ensure you have the following installed and configured:

1. Python 3.10+: The server is built on Python.
2. Git: For cloning the repository.
3. uv: A fast Python package installer. You can find installation instructions at the official uv documentation.
4. API Keys: You will need at least one API key from a supported provider to use the models.

Supported providers for which you can obtain API keys include:

• OpenRouter
• Gemini (Google)
• OpenAI
• Azure OpenAI
• X.AI (Grok)
• DIAL
• Ollama (for local models)

Sources: README.md

Installation and Setup

There are two primary methods for installing and setting up the Zen MCP server. The recommended approach is using the automatic setup script.

Automatic Setup (Linux/macOS)

The run-server.sh script automates the entire setup process. It is the recommended method for Linux and macOS users.

This diagram illustrates the workflow of the run-server.sh script.

The script performs the following actions:

1. Checks if uv is installed.
2. Creates a Python virtual environment named .zen_venv.
3. Installs all required Python packages listed in requirements.txt.
4. Creates a .env file from .env.example if one does not exist, which is used for storing API keys and other configurations.
5. Launches the Uvicorn server to run the main application.

To run the automatic setup:

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

Sources: run-server.sh, README.md, requirements.txt

Windows Setup

For Windows users, a PowerShell script run-server.ps1 is provided, which mirrors the functionality of the Linux/macOS shell script.

To run the setup on Windows:

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

Sources: run-server.ps1, README.md

Instant Setup with uvx

For advanced users, the server can be run directly from the git repository using uvx. This method requires configuring your MCP client's settings file (e.g., ~/.claude/settings.json) to execute the command.

// Add to ~/.claude/settings.json or .mcp.json
{
  "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"
      }
    }
  }
}

This configuration uses uvx to fetch and run the server from the GitHub repository directly, passing environment variables for API keys and tool settings.

Sources: README.md

Configuration

The server is configured primarily through environment variables, which are loaded from a .env file in the project's root directory. When you first run the setup script, .env.example is copied to .env. You must edit this file to add your API keys.

Sources: run-server.sh:26-29, README.md

Key Configuration Options

The following table details important configuration variables found in config.py that can be set in your .env file.

Variable	Description	Default Value
LOG_LEVEL	Sets the logging level for the application.	INFO
DEFAULT_MODEL	The default model to use if none is specified. auto enables automatic model selection.	auto
ENABLED_TOOLS	A comma-separated list of tools to enable. If empty, all tools are enabled except those in DISABLED_TOOLS.	""
DISABLED_TOOLS	A comma-separated list of tools to disable. This is processed after ENABLED_TOOLS.	analyze,refactor,testgen,secaudit,docgen,tracer
CONVERSATION_TIMEOUT_HOURS	The number of hours after which an inactive conversation thread is cleared.	6
MAX_CONVERSATION_TURNS	The maximum number of turns to keep in a conversation's memory.	50
GEMINI_API_KEY	API key for Google Gemini models.	""
OPENAI_API_KEY	API key for OpenAI models.	""
ANTHROPIC_API_KEY	API key for Anthropic models.	""

Sources: config.py:16-102, README.md

To enable a disabled tool like analyze, you would remove it from the DISABLED_TOOLS list in your .env file.

# .env example
# To enable analyze, remove it from the list
DISABLED_TOOLS=refactor,testgen,secaudit,docgen,tracer

Sources: README.md

Usage

Once the server is running, you can start sending requests from your configured MCP client (e.g., Claude Code, Cursor). You can invoke specific tools and models directly in your prompts.

Example Prompts:

"Use zen to analyze this code for security issues with gemini pro"
"Debug this error with o3 and then get flash to suggest optimizations"
"clink with cli_name=\"gemini cli\" role=\"planner\" to draft a phased rollout plan"

The server will parse these requests, invoke the corresponding tools (like analyze, debug, or clink), and orchestrate the interaction with the specified AI models.

Sources: README.md

Development Commands

For development, you can use the commands outlined in AGENTS.md. First, activate the virtual environment:

source .zen_venv/bin/activate

Then you can run quality checks or tests:

# Run Ruff, Black, isort, and pytest
./code_quality_checks.sh

# Run a specific test file
pytest tests/test_auto_mode_model_listing.py -q

Sources: AGENTS.md