Zoo Model Context Protocol (MCP) Server

An MCP server housing various Zoo built utilities

Prerequisites

A Zoo account. Run uvx zoo-mcp auth login once before starting the server. The command opens your browser and prints a verification URL and code. The server reuses your saved login; public tools also work without login.

You can also use an 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

Manage device login explicitly:

uvx zoo-mcp auth login
uvx zoo-mcp auth login --no-browser
uvx zoo-mcp auth status
uvx zoo-mcp auth logout

Logins are saved per API origin in your system credential store using keyring: macOS Keychain, Windows Credential Locker, or a supported Linux keyring. On headless systems without an available keyring, set ZOO_API_TOKEN instead. Status never displays tokens. Logout removes only the saved login for the current origin; restart running servers afterward. If your login expires or is revoked, run auth login again and restart the server. If the login command fails because of a network error, run it again to retry. Server startup never opens a browser. Device authorization and polling use requests-oauth2client. Device login requires the API's dedicated Zoo MCP device client registration.

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 client configuration from Python

Local entry points capture credentials when Zoo MCP is imported at startup. Token precedence is KITTYCAD_API_TOKEN, ZOO_API_TOKEN, then the registry's ZOO_TOKEN alias. Any explicit environment token bypasses saved/device login. API origin precedence is ZOO_HOST, KITTYCAD_HOST, then https://api.zoo.dev. Saved logins never cross API origins.

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

from zoo_mcp.client_config import ZooClientConfig, use_client_config
from zoo_mcp.server import mcp

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

The context supplies the same token, origin, and headers to the KittyCAD SDK and KCL session constructors and restores the previous configuration on exit. New calls can use refreshed configuration. Finish child tasks before leaving their configuration context. An explicit configuration context also prevents the server lifespan from loading a saved local login. Hosted workers and embeddings should

... View full README on GitHub