Zoo MCP server

Zoo Model Context Protocol (MCP) Server

An MCP server housing various Zoo built utilities

<!-- mcp-name: io.github.KittyCAD/zoo-mcp -->

Prerequisites

1. An API key for Zoo, get one here
2. An environment variable ZOOAPITOKEN set to your API key

export ZOO_API_TOKEN="your_api_key_here"

Installation

1. Ensure uv has been installed

1. Create a uv environment

uv venv

1. Activate your uv environment (Optional)

1. Install the package from GitHub

uv pip install git+ssh://git@github.com/KittyCAD/mcp.git

Running the Server

The server can be started by using uvx

uvx zoo-mcp

The server can be started locally by using uv and the zoo_mcp module

uv run -m zoo_mcp

The server can also be run with the mcp package

uv run mcp run src/zoo_mcp/server.py

Prebuilt binaries

Each GitHub release also attaches standalone executables (built with PyInstaller) for Linux (x8664, arm64), macOS (arm64, x8664), and Windows (x8664) — no Python toolchain required. Download the binary for your platform, set ZOOAPI_TOKEN, and run it directly, e.g.:

ZOO_API_TOKEN="your_api_key_here" ./zoo-mcp-linux-x86_64

The binaries are not code-signed, so macOS Gatekeeper and Windows SmartScreen may warn on first run.

Integrations

The server can be used as is by running the server or importing directly into your python code.

from zoo_mcp.server import mcp

mcp.run()

Individual tools can be used in your own python code as well. At Zoo we use zoo-mcp like this with ZooKeeper to save on resources. Instead of spinning up one MCP server per agent, each agent in a sense "embeds" the server in their own runtime. It has the additional benefit of preventing shared state.

from mcp.server.mcpserver import MCPServer
from zoo_mcp.zoo_tools import ResultZooExecuteKcl, zoo_execute_kcl

mcp = MCPServer(name="My Example Server")

@mcp.tool()
async def my_execute_kcl(kcl_code: str) -> ResultZooExecuteKcl:
    """
    Example tool that uses the zoo_execute_kcl function from zoo_mcp.zoo_tools
    """
    return await zoo_execute_kcl(kcl_code=kcl_code)

The server can be integrated with Claude desktop using the following command

uv run mcp install src/zoo_mcp/server.py

The server can also be integrated with Claude Code using the following command

claude mcp add --scope project "Zoo-MCP" uv -- --directory "$PWD"/src/zoo_mcp run server.py

The server can also be tested using the MCP Inspector

uv run mcp dev src/zoo_mcp/server.py

For running with codex-cli

codex \
  -c 'mcp_servers.zoo.command="uvx"' \
  -c 'mcp_servers.zoo.args=["zoo-mcp"]' \
  -c mcp_servers.zoo.env.ZOO_API_TOKEN="$ZOO_API_TOKEN"

You can also use the helper script included in this repo:

./codex-zoo.sh

The script prompts for a request, runs Codex with the Zoo MCP server, and saves a JSONL transcript (including token usage) to codex-run-.jsonl.

Architecture

Tools are defined in src/zoomcp/.py, where they are then imported into src/zoo_mcp/server.py and tied to actual @mcp.tool() decorated functions.

Shortened. The full README is on GitHub.