Running Locally

Relevant source files

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

• run-server.sh
• run-server.ps1
• run_dev_version.py
• README.md
• AGENTS.md
• CLAUDE.md

This document provides instructions for setting up and running the Zen MCP Server on a local machine for development and testing. The primary method involves using platform-specific setup scripts that automate dependency management and server execution.

The project includes scripts for both Unix-like systems (Linux, macOS) and Windows, ensuring a consistent setup experience. These scripts handle the creation of a Python virtual environment, installation of required packages, and launching of the server application. For more advanced development, direct execution via Python and specific testing commands are also available.

Prerequisites

Before running the server, you must have the following software installed:

• Python 3.10+
• Git
• uv (The setup scripts will attempt to check for it)

You will also need API keys for the AI providers you intend to use. These should be configured in the .env file after the initial setup.

Sources: README.md:128-130

Quick Start via Setup Scripts

The recommended way to run the server is by using the provided setup scripts. These scripts handle all necessary setup steps, from creating a virtual environment to installing dependencies and launching the server.

Sources: README.md:135-142, AGENTS.md:12, CLAUDE.md:49-54

Unix-like Systems (Linux, macOS)

The run-server.sh script is the main entry point for Unix-like systems. It automates the entire setup and launch process.

Sources: README.md:141-142, AGENTS.md:12

Execution Flow

The diagram below illustrates the sequence of operations performed by the run-server.sh script.

Commands

1. Clone the repository:

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

   Sources: README.md:138-139

2. Run the setup script:
   This command handles virtual environment creation, dependency installation, and server launch.

   ./run-server.sh
   

   Sources: README.md:142, AGENTS.md:12

3. Check Server Status:
   The -f flag can be used to check if the server process is already running.

   ./run-server.sh -f
   

   Sources: run-server.sh:10-16, CLAUDE.md:66

Windows

For Windows users, the run-server.ps1 PowerShell script provides equivalent functionality to the Unix shell script.

Execution Flow

The script performs the following actions:

1. Checks if the uv command is available.
2. Creates a .zen_venv virtual environment if it doesn't exist.
3. Activates the virtual environment.
4. Creates a .env file from .env.example if one is not present.
5. Installs dependencies listed in requirements.txt and requirements-dev.txt using uv pip install.
6. Starts the server.py application.

Sources: run-server.ps1

Command

.\run-server.ps1

Sources: run-server.ps1

Development Workflow

For active development, you may need to interact with the environment and run tests or quality checks directly.

Sources: AGENTS.md:10-25, CLAUDE.md:56-64

Activating the Virtual Environment

Before running commands directly, activate the Python virtual environment created by the setup scripts.

source .zen_venv/bin/activate

Sources: AGENTS.md:11, CLAUDE.md:57

Running Code Quality Checks

The project includes a script to run a suite of code quality tools, including Ruff, Black, and isort.

./code_quality_checks.sh

Sources: AGENTS.md:13-17, CLAUDE.md:60

Running Tests

The pytest framework is used for testing. You can run all tests or target specific files.

# Run all tests
pytest -q

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

Sources: AGENTS.md:21-25

Running a Development Version

The run_dev_version.py script provides an alternative way to start the server, which may be useful for debugging. It directly imports and runs the main function from server.py.

# run_dev_version.py
if __name__ == "__main__":
    from server import main
    main()

Sources: run_dev_version.py:1-3

To run it:

python run_dev_version.py

Configuration

Local execution is configured primarily through an .env file and optional MCP client settings.

Environment Variables

The setup scripts create a .env file from .env.example on the first run. This file is used to store API keys and other configuration.

Sources: run-server.sh:31-33, run-server.ps1:19-21, README.md:121

Key configuration options from the .env file include:

Variable	Description	Default Source
DISABLED_TOOLS	A comma-separated list of tools to disable to save context window space.	README.md:204
GEMINI_API_KEY	API key for Google Gemini models.	README.md:151
OPENAI_API_KEY	API key for OpenAI models.	README.md:152
LOG_LEVEL	Sets the logging verbosity (e.g., INFO, DEBUG).	README.md:214

Sources: README.md:149-220

MCP Client Configuration

Alternatively, configuration can be managed within an MCP client's settings file, such as ~/.claude/settings.json. This method allows for specifying environment variables directly within the JSON configuration.

// Example from README.md
{
  "mcpServers": {
    "zen": {
      "env": {
        "DISABLED_TOOLS": "analyze,refactor,testgen,secaudit,docgen,tracer",
        "DEFAULT_MODEL": "auto",
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Sources: README.md:145-162

Summary

Running the Zen MCP Server locally is streamlined through the run-server.sh and run-server.ps1 scripts, which automate the entire setup process. These scripts ensure a consistent Python environment, handle dependencies, and configure the application for first use. For developers, additional commands are available for activating the virtual environment, running tests, and performing code quality checks, supporting a comprehensive local development and testing workflow.