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 ZOO_API_TOKEN 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://[email protected]/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

Streamable HTTP

The server uses stdio by default. To serve the same tools over Streamable HTTP:

uvx zoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# From a local checkout:
uv run -m zoo_mcp --transport streamable-http

Connect an MCP client to http://127.0.0.1:8000/mcp. The SDK manages HTTP sessions and streaming responses. --host and --port configure the HTTP listener; their defaults are 127.0.0.1 and 8000.

Supplying credentials from Python

Local entry points capture credentials when Zoo MCP is imported at startup. They accept ZOO_API_TOKEN, KITTYCAD_API_TOKEN, or the registry's ZOO_TOKEN alias, and ZOO_HOST or KITTYCAD_HOST for the API origin.

Applications can supply credentials explicitly without changing the process environment or adding authentication arguments to MCP tools:

from zoo_mcp.credentials import ZooCredentials, use_credentials
from zoo_mcp.server import mcp

with use_credentials(ZooCredentials(token=api_token, base_url=api_origin)):
    result = await mcp.call_tool("list_org_datasets", {})

The context supplies the same token and origin to the KittyCAD SDK and KCL session constructors and restores the previous configuration on exit. New calls can use refreshed credentials. Finish child tasks before leaving their credential context.

Credential contexts configure downstream calls. Applications serving different owners must also isolate their process-wide modeling sessions and workspaces.

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.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-<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.

KCL execution and persistent modeling sessions use the CPU engine pool. Isolated KCL snapshots temporarily enable CPU rendering. Persistent sessions initialize rendering on the first snapshot, selection, highlight, or camera tool and retain it until the session is stopped, preserving visual state across calls. Exports, measurements, and geometry queries do not initialize graphics.

The KCL samples tools list and search public Aquarium projects from the Zoo API. Pass the returned name (a public project ID) to get_kcl_sample to download its KCL sources. Filenames preserve project-relative paths, including subdirectories. These public tools do not require an API token. The multipleFiles field in list/search results is a hint until the project has been downloaded.

As of 0.28.0, execute_kcl and exec_kcl_project run mock execution before real execution and return separate mock_preflight and real_execution objects. Each contains status (succeeded, failed, or not_run), message, and diagnostics grouped by severity. Stage messages are short summaries; the top-level message retains the full report for existing callers. Failed stages also expose error_family, including ZooMCPTimeoutError for session timeouts. Mock errors or an aborted mock execution return immediately with ok: false and real_execution.status: "not_run". Mock warnings remain in mock_preflight.diagnostics even if real execution fails. The known planeOf mock-engine limitation is reported as a warning so the real engine can evaluate it; other mock errors still block execution. Session responses expose mock diagnostics; the engine does not return real-stage diagnostics for session execution.

Path inputs capture the entrypoint, its transitive imports (including linked modules and glTF buffers), and project.toml once. Both stages use that copy without scanning unrelated files in the containing directory. Dependencies and symlink targets must stay inside the entrypoint's directory; external paths are rejected before file reads or execution. Transient local real-execution failures retain their bounded retries using the same copy without repeating mock execution. Diagnostics refer to the original source paths. Inline kcl_code accepts self-contained code and standard-library imports; filesystem imports require kcl_path so their dependencies can be captured within an explicit directory. exec_kcl_project now returns this structured result instead of a path string: check ok, then read path_artifact_graph on session success. The standalone mock_execute_kcl tool continues to return its existing boolean/message pair.

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