Zoo MCP

🚀 Zoo Model Context Protocol (MCP) Server

The MCP server that houses various Zoo built utilities.

🚀 Quick Start

Prerequisites

1. Obtain an API key for Zoo here.
2. Set the environment variable ZOO_API_TOKEN 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/zoo-mcp.git

Running the Server

• Start the server using uvx:

uvx zoo-mcp

• Start the server locally using uv and the zoo_mcp module:

uv run -m zoo_mcp

• Run the server with the mcp package:

uv run mcp run src/zoo_mcp/server.py

💻 Usage Examples

Integrations

• Use the server by running the server or importing directly into your Python code:

from zoo_mcp.server import mcp

mcp.run()

• Use individual tools in your own Python code:

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)

• Integrate the server with Claude desktop using the following command:

uv run mcp install src/zoo_mcp/server.py

• Integrate the server with Claude Code using the following command:

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

• Test the server using the MCP Inspector:

uv run mcp dev src/zoo_mcp/server.py

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

🔧 Technical Details

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.

• Use ruff for linting and formatting:

uvx ruff check
uvx ruff format

• Use ty for type checking:

uvx ty check

Testing

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

uv run pytest -n auto