Zoo MCP Server

What is Zoo MCP Server about?

Zoo MCP Server provides a ready‑to‑run Model Context Protocol (MCP) server that bundles a set of Zoo utilities such as KCL execution, CAD file import, and session management. The server can be accessed via standard input/output or over a streamable‑HTTP endpoint, allowing developers to embed modeling capabilities directly inside their applications or AI agents.

How to use Zoo MCP Server?

1. Prerequisites – Obtain a Zoo API token and export it as ZUI_API_TOKEN.
2. Installation – Install the uv tool, create a virtual environment (uv venv), and install the package from GitHub:

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

3. Running the server – Choose one of the following methods:
   • Simple CLI: uvx zoo-mcp
   • Module execution: uv run -m zoo_mcp
   • With the MCP SDK: uv run mcp run src/zoo_mcp/server.py
4. Streamable HTTP – Serve tools over HTTP:

   uvx zoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000
   

   Clients connect to http://127.0.0.1:8000/mcp.
5. Embedding – Import and run programmatically:

   from zoo_mcp.server import mcp
   mcp.run()
   

Key Features

• Multiple transport modes – stdio (default) and streamable‑HTTP.
• Pre‑built binaries for Linux, macOS, and Windows (no Python required).
• Rich toolset in src/zoo_mcp/zoo_tools.py covering KCL execution, project handling, and CAD import.
• Session management – persistent modeling sessions with explicit start/stop APIs.
• Mock‑preflight – safety checks run before real execution, returning detailed diagnostics.
• Integration helpers for Claude Desktop, Claude Code, MCP Inspector, and Codex‑CLI.
• Testing & linting – built‑in pytest suite, Ruff for formatting, Ty for type checking.

Use Cases

• AI agents that need on‑demand geometry generation or modification.
• IDE extensions offering live KCL preview via an MCP client.
• Automation pipelines that batch‑process CAD files or run KCL scripts.
• Research projects evaluating modeling workflows without spinning up separate servers for each agent.
• CLI utilities that invoke Zoo capabilities directly from the command line.

FAQ

Q: Do I need Python installed? A: Yes, unless you use one of the pre‑built binaries which bundle the interpreter.

Q: How do I set the API token? A: Export ZOO_API_TOKEN in your shell before starting the server.

Q: Can I run the server behind a firewall? A: When using the HTTP transport, configure --host and --port to bind to an internal address.

Q: What is the difference between execute_kcl and exec_kcl_project? A: execute_kcl runs a single KCL snippet, while exec_kcl_project handles a full project directory and returns a structured result containing mock and real execution diagnostics.

Q: How are mock errors handled? A: Mock failures abort the real execution and return ok: false with real_execution.status set to "not_run". Warnings are propagated but do not stop execution.

Q: How do I contribute? A: Fork the repository, make changes, and submit a pull request. All contributions must pass the test suite and Ruff linting.

Zoo Model Context Protocol (MCP) Server

An MCP server housing various Zoo built utilities

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

2. Create a uv environment

   uv venv
   

3. Activate your uv environment (Optional)

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

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.

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.

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