{
  "markdown": "# build123d-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/build123d-mcp)](https://pypi.org/project/build123d-mcp/)\n[![Downloads](https://static.pepy.tech/badge/build123d-mcp/month)](https://pepy.tech/project/build123d-mcp)\n[![Python](https://img.shields.io/pypi/pyversions/build123d-mcp)](https://pypi.org/project/build123d-mcp/)\n[![CI](https://github.com/pzfreo/build123d-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/build123d-mcp/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.pzfreo%2Fbuild123d--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=build123d)\n[![build123d-mcp MCP server](https://glama.ai/mcp/servers/pzfreo/build123d-mcp/badges/score.svg)](https://glama.ai/mcp/servers/pzfreo/build123d-mcp)\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=build123d-mcp&config=%7B%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22tool%22%2C%22run%22%2C%22--python%22%2C%223.12%22%2C%22build123d-mcp%40latest%22%5D%7D)\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=build123d-mcp&config=eyJjb21tYW5kIjoidXYiLCJhcmdzIjpbInRvb2wiLCJydW4iLCItLXB5dGhvbiIsIjMuMTIiLCJidWlsZDEyM2QtbWNwQGxhdGVzdCJdfQ==)\n\nGive your AI CAD eyes.\n\nbuild123d-mcp is not a standalone chatbot or CAD program. It is a CAD toolbox\nthat an AI/LLM app can use through MCP.\n\nWith an LLM app such as Claude, Cursor, VS Code, Continue, Cline, or Codex CLI,\nbuild123d-mcp lets the assistant create build123d CAD models, render previews,\nmeasure geometry, fix mistakes, and export files such as STEP, STL, SVG, and\nDXF. Instead of writing a whole CAD script blindly, the assistant can build a\npart in small steps and check the result as it goes.\n\nOn the public [CADGenBench](https://huggingface.co/spaces/HuggingAI4Engineering/CADGenBench)\nleaderboard in June 2026, using build123d-mcp raised the same model's score from\n0.360 to 0.457 and CAD validity from 88% to 100%.\n\n## Pick Your Setup\n\nMost users should start with the local MCP server setup:\n\n- You use Claude, Cursor, VS Code, Continue, Cline, or Codex CLI on your own\n  machine.\n- Your AI app starts `build123d-mcp` as a local subprocess.\n- You do not need to clone this repository.\n\nUse GitHub Codespaces instead if you want a browser-only trial or a ready-made\ndevelopment workspace with Copilot Chat, Python, uv, and the CAD dependencies\nalready installed.\n\nUse HTTP mode only for advanced deployments where you are hosting the MCP server\nyourself.\n\n## Quick Start\n\nYou need:\n\n- [uv](https://github.com/astral-sh/uv)\n- An AI/LLM app that supports MCP, such as Claude Code, Claude Desktop, Cursor,\n  VS Code, Continue, Cline, or Codex CLI\n\nNo repository clone is needed for normal use. First check that the package can\nstart:\n\n```bash\nuv tool run --python 3.12 build123d-mcp@latest --version\n```\n\nThen add the same command to your AI app's MCP config. The common pieces are:\n\n```text\ncommand: uv\nargs:    [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n```\n\n> Python 3.11, 3.12, 3.13, and 3.14 are supported. The examples use 3.12 because\n> it is a conservative default, and uv can download it if you do not already\n> have it installed.\n\n## Connect To Your AI App\n\nThe pieces are:\n\n- The LLM app is where you chat with the assistant.\n- MCP is the connection that lets the assistant call tools.\n- build123d-mcp is the CAD tool server the assistant calls.\n\nThe server normally runs over stdio. Your AI app starts it as a local subprocess\nwhen it needs the CAD tools.\n\n### Claude Code\n\nAdd this to your project's `.mcp.json`, or to `~/.claude/mcp.json` for global\nuse:\n\n```json\n{\n  \"mcpServers\": {\n    \"build123d-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n    }\n  }\n}\n```\n\nRestart Claude Code after editing.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,\nor `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"build123d-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### Cursor\n\nOpen **Settings -> MCP** and add a new server entry, or edit\n`~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"build123d-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n    }\n  }\n}\n```\n\n### VS Code, Continue, Cline, Codex CLI\n\nUse the same command and arguments in whichever MCP config your AI app or\nextension reads. The exact filename varies by app, but the server command is the\nsame:\n\n```text\ncommand: uv\nargs:    [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n```\n\nFor GitHub Copilot MCP support in VS Code, this repository includes a\n`.vscode/mcp.json` for development checkouts and Codespaces. For another\nworkspace, the config looks like this:\n\n```json\n{\n  \"servers\": {\n    \"build123d-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"tool\", \"run\", \"--python\", \"3.12\", \"build123d-mcp@latest\"]\n    }\n  }\n}\n```\n\n## First Test Prompt\n\nOnce your AI app is connected to the server, ask your assistant something\nconcrete:\n\n```text\nUse build123d-mcp to make a 60 mm x 40 mm x 6 mm mounting plate with two\n5 mm through holes 40 mm apart. Render it, measure it, then export STEP and STL.\n```\n\nThe useful loop is:\n\n1. Build one feature at a time.\n2. Render or measure after important steps.\n3. Validate before export.\n4. Export the final part.\n\nIf something goes wrong, ask the assistant to inspect `last_error`, repair the\nscript, and try the next smaller step.\n\nGood prompts usually ask the assistant to use the MCP tools explicitly and to\nverify the result before exporting. For example:\n\n```text\nUse build123d-mcp. Build this incrementally, render after the main features,\nmeasure the final dimensions, run validate(), and export STEP if it passes.\n```\n\n## Try It In GitHub Codespaces With Copilot\n\nYou can also run the project in a browser with GitHub Codespaces:\n\n[Open in GitHub Codespaces](https://codespaces.new/pzfreo/build123d-mcp)\n\nFor a beginner, this is the closest path to \"GitHub-hosted LLM + MCP\":\n\n- GitHub Codespaces gives you VS Code in the browser.\n- GitHub Copilot Chat gives you the LLM assistant.\n- build123d-mcp runs inside the codespace as the MCP CAD tool server.\n\nYou need GitHub Copilot access for the LLM part. The codespace itself gives you\na throwaway workspace with the project already checked out and the right\nPython/CAD dependencies installed. It is useful when you want to:\n\n- Try the project without changing your laptop setup\n- Run the tests before making a contribution\n- Use Copilot Chat and build123d-mcp together in the same browser workspace\n\nGitHub's docs cover:\n\n- [Using Copilot in Codespaces](https://docs.github.com/en/codespaces/reference/using-github-copilot-in-github-codespaces)\n- [Extending Copilot Chat with MCP](https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-chat-with-mcp)\n\nThis repository includes a dev container that installs Python 3.12, uv, and the\nLinux display packages needed for headless rendering. It also installs the\nGitHub Copilot VS Code extensions and includes a workspace MCP config at\n`.vscode/mcp.json`.\n\nWhen the codespace opens, it runs:\n\n```bash\nuv sync --all-groups\n```\n\nTo check the development install:\n\n```bash\nuv run build123d-mcp --version\nuv run pytest\n```\n\nTo use Copilot with the local CAD server:\n\n1. Open the codespace.\n2. Wait for setup to finish.\n3. Open Copilot Chat and choose Agent mode.\n4. Open `.vscode/mcp.json` and start the `build123d-mcp` server if VS Code has\n   not started it already.\n5. Ask the first test prompt from the previous section.\n\nThe Codespaces MCP config points at the local checkout rather than the PyPI\npackage:\n\n```json\n{\n  \"servers\": {\n    \"build123d-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"build123d-mcp\"]\n    }\n  }\n}\n```\n\nCodespaces is a good fit for trying the project, contributing, or using GitHub\nCopilot and build123d-mcp in one remote environment. For desktop AI apps on your\nown machine, the normal `uv tool run ... build123d-mcp@latest` setup is simpler\nbecause those apps expect to start the MCP server locally.\n\n## What It Can Do\n\nbuild123d-mcp gives an assistant tools to:\n\n- Execute build123d code in a persistent CAD session\n- Render PNG, SVG, and DXF previews\n- Measure volume, area, bounding boxes, topology, and centers of mass\n- Find holes, bosses, countersinks, and hole patterns\n- Check printability, fit/alignment comparisons, and export validity\n- Import STEP/STL files for comparison\n- Export STEP, STL, DXF, SVG, or multiple formats at once\n- Save and restore session snapshots\n- Produce 2D engineering drawing previews\n\nFor the complete tool and resource reference, see [llms.md](llms.md).\n\n## Guidance For Assistants\n\nThe server includes workflow guidance that helps assistants use the CAD loop\nproperly. This is especially useful in coding agents that read project guidance\nfiles.\n\nAfter connecting the server, ask your assistant to call `install_skill` for the\nworkflow you need:\n\n```text\ninstall_skill(target=\"agents-md\", skill=\"modeling\")\ninstall_skill(target=\"agents-md\", skill=\"drawing\")\ninstall_skill(target=\"agents-md\", skill=\"repair\")\n```\n\n`install_skill` also supports `target=\"claude\"`, `\"cursor\"`, and `\"windsurf\"`.\nUse `skill=\"modeling\"` for 3D parts, `skill=\"drawing\"` for engineering drawings,\nand `skill=\"repair\"` when a solid fails validation.\n\nYou can also paste [default_prompt.md](default_prompt.md) into your AI app as a\nsystem prompt.\n\n## Developer Setup\n\nFor local development:\n\n```bash\ngit clone https://github.com/pzfreo/build123d-mcp.git\ncd build123d-mcp\nuv sync --all-groups\nuv run build123d-mcp --version\nuv run pytest\n```\n\nTo run the server from this checkout in an AI app, use:\n\n```text\ncommand: uv\nargs:    [\"run\", \"build123d-mcp\"]\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n\n## Advanced Use\n\nThe default stdio transport gives each app process its own isolated session.\nHTTP mode is available for web, container, or remote deployments:\n\n```bash\nuv tool run --python 3.12 \"build123d-mcp[http]@latest\" \\\n  --transport http --host 127.0.0.1 --port 8000\n```\n\nHTTP-capable apps then connect to:\n\n```text\nhttp://localhost:8000/mcp\n```\n\nHTTP mode has no built-in authentication and uses one shared CAD session unless\nthe host provides per-request session middleware. Do not expose it to multiple\nusers directly.\n\nOther advanced topics:\n\n- Security model and sandboxing: [security.md](security.md)\n- Complete tool reference: [llms.md](llms.md)\n- Live session viewer: [docs/live-viewer.md](docs/live-viewer.md)\n- Changelog: [CHANGELOG.md](CHANGELOG.md)\n\n## Status\n\nActive development.\n\n<!-- mcp-name: io.github.pzfreo/build123d-mcp -->\n",
  "bytes": 11161,
  "sha": "5ed718e36fd0537b079e1f670b6088313edbb356bfcd34bedc782b5279a14c4d",
  "repo_slug": "pzfreo/build123d-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pzfreo_build123d_mcp_8b2cb19e/readme"
}