Zoo Model Context Protocol (MCP) Server

An MCP server housing various Zoo built utilities

Prerequisites

An API key for Zoo, get one here
An environment variable ZOO_API_TOKEN set to your API key
```
export ZOO_API_TOKEN="your_api_key_here"
```

Installation

Ensure uv has been installed
Create a uv environment
```
uv venv
```
Activate your uv environment (Optional)

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 (x86_64, arm64), macOS (arm64, x86_64), and Windows (x86_64) — no Python toolchain required. Download the binary for your platform, set ZOO_API_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.fastmcp import FastMCP
from zoo_mcp.zoo_tools import ResultZooExecuteKcl, zoo_execute_kcl

mcp = FastMCP(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-<timestamp>.jsonl.

Architecture

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

src/zoo_mcp/zoo_tools.py acts as a large toolset to interact with Zoo's KCL and engine facilities. This source file houses other utilities like parse_unit or normalize_ext (normalizing file extensions).

Modeling scenes use explicit persistent sessions, with at most one session open per server process. Call get_modeling_sessions to recover its ID after a client reconnect, or call start_modeling_session when none exists. Populate the session with execute_kcl, exec_kcl_project, or import_cad_file; pass the same session_id to snapshot and modeling tools; then call stop_modeling_session when finished.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository

PRs will need to pass tests and linting before being merged.

ruff is used for linting and formatting.

uvx ruff check
uvx ruff format

ty is used for type checking.

uvx ty check

Testing

The server includes tests located in tests. To run the tests, use the following command:

uv run pytest -n auto

Release files for zoo_mcp 0.26.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for zoo_mcp 0.26.6
File	Interpreter	ABI	Platform	Reset
zoo_mcp-0.26.6-py3-none-any.whl 54.5 kB Sep 2, 2026	Python 3	none	any	Details

Release files / zoo_mcp-0.26.6-py3-none-any.whl

Download URL	zoo_mcp-0.26.6-py3-none-any.whl
Size	54.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a0a97417347381ab41bd2a477ecdd079077adfbfb881c17c15b0d96c0293fc1a`
BLAKE2b-256 checksum How to use checksums	`6f726a3d6ac894d7b4aa2bfec471ccd46a3f4843eb5b637f1587166663929778`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`