# zoo-mcp

An MCP server that hands your agent Zoo's CAD tools: run KCL code, import CAD files, take snapshots and measure models.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10
- Author: KittyCAD
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/KittyCAD/mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/zoo-mcp

## What it does

The server wraps Zoo's API and exposes it as agent tools. `execute_kcl` and `exec_kcl_project` run KCL code, `import_cad_file` brings in existing models, and `snapshot` plus the camera tools show the scene. A separate set of tools lists and searches public Aquarium projects and downloads their KCL sources — those calls need no token.

Modeling runs on explicit sessions, one per server process at most. After a client reconnect, `get_modeling_session` returns the session ID; when none exists, `start_modeling_session` opens one. Pass the same `session_id` to snapshots and modeling tools, then close it with `stop_modeling_session`. Rendering starts on the first snapshot, selection, highlight or camera call and stays on until the session stops, so visual state survives between calls. Exports, measurements and geometry queries never spin up graphics.

You need a Zoo API key in `ZOO_API_TOKEN`; the server will not start without it. Local entry points also read `KITTYCAD_API_TOKEN` and the `ZOO_TOKEN` alias, with `ZOO_HOST` or `KITTYCAD_HOST` setting the API origin. Stdio is the default transport. For Streamable HTTP, launch with `--transport streamable-http` and point the client at `http://127.0.0.1:8000/mcp`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `ZOO_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add zoo-mcp -e ZOO_TOKEN=<ZOO_TOKEN> -- uvx zoo_mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zoo_mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add zoo-mcp --env ZOO_TOKEN=<ZOO_TOKEN> -- uvx zoo_mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zoo_mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "zoo-mcp": {
            "command": "uvx",
            "args": [
                "zoo_mcp"
            ],
            "env": {
                "ZOO_TOKEN": "<ZOO_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zoo_mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "zoo-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "zoo_mcp"
            ],
            "env": {
                "ZOO_TOKEN": "<ZOO_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zoo_mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ZOO_TOKEN=<ZOO_TOKEN> zoo-mcp uvx zoo_mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zoo_mcp <command>

## When to use it
- run KCL code from the agent and read the result
- bring a CAD file into a modeling session
- snapshot a model and inspect its current state
- find a public Aquarium project and download its KCL sources
- measure geometry without starting the renderer

## Example prompts
- Run this KCL code and show me the result
- Import `bracket.step` into the modeling session and take a snapshot
- Find the public Aquarium project by name and download its KCL sources

## Similar
- [cad](https://affpapa.org/en/nevibecode/skills/cad.md) — skill · 14000 installs
- [text-to-cad-harness](https://affpapa.org/en/nevibecode/skills/text-to-cad-harness.md) — skill · 380 installs
- [PartCAD](https://affpapa.org/en/nevibecode/mcp/partcad.md) — MCP server · ★ 509
- [ClassCAD](https://affpapa.org/en/nevibecode/mcp/classcad.md) — MCP server · ★ 171
- [SolidWorks](https://affpapa.org/en/nevibecode/mcp/solidworks.md) — MCP server · ★ 19
- [cli-anything-freecad](https://affpapa.org/en/nevibecode/skills/cli-anything-freecad.md) — skill · 650 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md