Zoo Model Context Protocol

You can run a dedicated Zoo MCP server that hosts various Zoo utilities, exposing them for easy integration with your applications and code editors. This server lets you access Zoo tools through a consistent MCP interface, letting you build and test tools, and integrate with clients and automation workflows.

How to use

You will start one of the Zoo MCP server runtimes and connect to it with an MCP client or import it directly into your Python code. The server provides a set of tools that you can call from your applications, enabling you to generate CAD from text, run fast machine-assisted workflows, and extend with your own tools. Use the standard start commands below to run the server locally, then interact with it from your client of choice by sending tool invocations through the MCP protocol.

How to install

Prerequisites and initial setup prepare your environment to run the Zoo MCP server.

export ZOO_API_TOKEN="your_api_key_here"

Create and activate a dedicated environment, then install the Zoo MCP server package from its source.

uv venv

Install the Zoo MCP package from the official repository using the Python package installer within your environment.

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

Integrations and usage notes

Run the server using one of several supported runtimes. The most direct local start method is to invoke the UV runtime with the MCP module, or to run the module directly via UV's Python support. You can also run the server via the MCP runner provided by the uvx toolchain.

uvx zoo-mcp

uv run -m zoo_mcp

uv run mcp run src/zoo_mcp/server.py

API and integration patterns

You can integrate tools directly into your Python projects by importing the server components and registering tools. This lets you call Zoo tools as native MCP endpoints within your application.

from zoo_mcp.server import mcp

mcp.run()

Example tools and usage

Two example capabilities shown in the project illustrate how to expose tools within your MCP server. You can adapt or extend these patterns to add your own tools.

from mcp.server.fastmcp import FastMCP
from zoo_mcp.ai_tools import text_to_cad

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

@mcp.tool()
async def my_text_text_to_cad(prompt: str) -> str:
    """
    Example tool that uses the text_to_cad function from zoo_mcp.tools
    """
    return await text_to_cad(prompt=prompt)

Starting with Claude or Codex tooling

You can integrate the Zoo MCP server with Claude or Codex tooling by using the provided runner commands to bind the MCP server into your workspace or editor.

uv run mcp install src/zoo_mcp/server.py

Testing and verification

Test the server interactions and endpoints with the included inspector or by running representative tool invocations from your client. You can verify that the MCP server exposes the expected endpoints and tool behaviors.

uv run mcp dev src/zoo_mcp/server.py

Codecs for Codex and CLI usage

If you are using Codex or a CLI-based workflow, you can configure and execute the MCP server with the demonstrated environment and startup commands to ensure a smooth integration flow.

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"

Running a quick helper script

You can use the helper script included in the repository to quickly start a Codex-driven session with the Zoo MCP server and generate a transcript for analysis.

./codex-zoo.sh

Available tools

FastMCP

A fast MCP client that enables quick function registration and tool invocation within the Zoo MCP server.

text_to_cad

Converts text prompts into CAD representations using Zoo AI tooling accessible through the MCP server.