{
  "markdown": "# Zoo Model Context Protocol (MCP) Server\n\nAn [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) housing various Zoo built utilities\n\n<!-- mcp-name: io.github.KittyCAD/zoo-mcp -->\n\n## Prerequisites\n\n1. An API key for Zoo, get one [here](https://zoo.dev/account)\n2. An environment variable `ZOO_API_TOKEN` set to your API key\n    ```bash\n    export ZOO_API_TOKEN=\"your_api_key_here\"\n    ```\n\n## Installation\n\n1. [Ensure uv has been installed](https://docs.astral.sh/uv/getting-started/installation/)\n\n2. [Create a uv environment](https://docs.astral.sh/uv/pip/environments/)\n    ```bash\n    uv venv\n    ```\n\n3. [Activate your uv environment (Optional)](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment)\n\n4. Install the package from GitHub\n    ```bash\n    uv pip install git+ssh://git@github.com/KittyCAD/mcp.git\n    ```\n\n## Running the Server\n\nThe server can be started by using [uvx](https://docs.astral.sh/uv/guides/tools/#running-tools)\n```bash\nuvx zoo-mcp\n```\n\nThe server can be started locally by using uv and the zoo_mcp module\n```bash\nuv run -m zoo_mcp\n```\n\nThe server can also be run with the [mcp package](https://github.com/modelcontextprotocol/python-sdk)\n```bash\nuv run mcp run src/zoo_mcp/server.py\n```\n\n### Prebuilt binaries\n\nEach [GitHub release](https://github.com/KittyCAD/mcp/releases) 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.:\n```bash\nZOO_API_TOKEN=\"your_api_key_here\" ./zoo-mcp-linux-x86_64\n```\n> The binaries are not code-signed, so macOS Gatekeeper and Windows SmartScreen may warn on first run.\n\n## Integrations\n\nThe server can be used as is by [running the server](#running-the-server) or importing directly into your python code.\n```python\nfrom zoo_mcp.server import mcp\n\nmcp.run()\n```\n\nIndividual tools can be used in your own python code as well. At Zoo we use\nzoo-mcp like this with ZooKeeper to save on resources. Instead of spinning up\none MCP server per agent, each agent in a sense \"embeds\" the server in their own\nruntime. It has the additional benefit of preventing shared state.\n\n```python\nfrom mcp.server.fastmcp import FastMCP\nfrom zoo_mcp.zoo_tools import ResultZooExecuteKcl, zoo_execute_kcl\n\nmcp = FastMCP(name=\"My Example Server\")\n\n\n@mcp.tool()\nasync def my_execute_kcl(kcl_code: str) -> ResultZooExecuteKcl:\n    \"\"\"\n    Example tool that uses the zoo_execute_kcl function from zoo_mcp.zoo_tools\n    \"\"\"\n    return await zoo_execute_kcl(kcl_code=kcl_code)\n```\n\nThe server can be integrated with [Claude desktop](https://claude.ai/download) using the following command\n```bash \nuv run mcp install src/zoo_mcp/server.py\n```\n\nThe server can also be integrated with [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) using the following command\n```bash\nclaude mcp add --scope project \"Zoo-MCP\" uv -- --directory \"$PWD\"/src/zoo_mcp run server.py\n```\n\nThe server can also be tested using the [MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector#python)\n```bash\nuv run mcp dev src/zoo_mcp/server.py\n```\n\nFor running with [codex-cli](https://github.com/openai/codex)\n```bash\ncodex \\\n  -c 'mcp_servers.zoo.command=\"uvx\"' \\\n  -c 'mcp_servers.zoo.args=[\"zoo-mcp\"]' \\\n  -c mcp_servers.zoo.env.ZOO_API_TOKEN=\"$ZOO_API_TOKEN\"\n```\n\nYou can also use the helper script included in this repo:\n```bash\n./codex-zoo.sh\n```\nThe 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`.\n\n## Architecture\n\nTools are defined in `src/zoo_mcp/*.py`, where they are then imported into\n`src/zoo_mcp/server.py` and tied to actual `@mcp.tool()` decorated functions.\n\n`src/zoo_mcp/zoo_tools.py` acts as a large toolset to interact with Zoo's KCL and\nengine facilities. This source file houses other utilities like `parse_unit` or\n`normalize_ext` (normalizing file extensions).\n\nModeling scenes use explicit persistent sessions, with at most one session open\nper server process. Call `get_modeling_sessions` to recover its ID after a client\nreconnect, or call `start_modeling_session` when none exists. Populate the\nsession with `execute_kcl`, `exec_kcl_project`, or `import_cad_file`; pass the\nsame `session_id` to `snapshot` and modeling tools; then call\n`stop_modeling_session` when finished.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/KittyCAD/mcp)\n\nPRs will need to pass tests and linting before being merged.\n\n### [ruff](https://docs.astral.sh/ruff/) is used for linting and formatting.\n```bash\nuvx ruff check\nuvx ruff format\n```\n\n### [ty](https://docs.astral.sh/ty/) is used for type checking.\n```bash\nuvx ty check\n```\n\n## Testing\n\nThe server includes tests located in [`tests`](`tests`). To run the tests, use the following command:\n```bash\nuv run pytest -n auto\n```\n",
  "bytes": 5074,
  "sha": "31be0f68988978e11f509b762c600594ca3d424fa31f2dc57d89c99e9ebaa850",
  "repo_slug": "kittycad/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kittycad_zoo_mcp_f94bbacd/readme"
}