# classcad.ai

> Everything that lets AI agents build and verify CAD models with ClassCAD, the CAD engine by AWV Informatik AG. The ClassCAD MCP server gives an agent a live CAD session: it writes JavaScript programs against the ClassCAD API, runs them with `run_script`, renders the model with `snapshot`, and proves the result with mass properties and geometry probes. The MCP is self-contained: it runs the ClassCAD engine itself (WebAssembly), so there is no server to set up and no key to configure; it needs a free classcad.ch account, signed in once per machine with one click.

If a user asked you to install the ClassCAD MCP, follow "Install" and then "Configure the host" for the host you are running in. It takes a minute or two.

## Install

Requirements: Node.js 20 or newer, and internet access on first use.

There is nothing to clone or build. Every host starts the server with this one command:

```bash
npx -y @awv-informatik/classcad-mcp@latest
```

Use it exactly like that in every config below: `@latest` makes npx fetch the newest release instead of reusing an older cached one.

- No environment variables are needed. Do not install a ClassCAD server (classcad-cli): it is optional, and the MCP runs its own engine without it.
- npx may warn that sharp's install script was not run. That is fine: sharp ships prebuilt binaries.
- Only if npx cannot fetch the package at all, see "Last resort: build from source" below.

## Configure the host

No ClassCAD settings are needed. After configuring, the host has to start a new session (or be restarted) before the classcad tools appear.

Claude Code (terminal, and the Code tab of the Claude desktop app):

```bash
claude mcp add classcad --scope user -- npx -y @awv-informatik/classcad-mcp@latest
```

Check with `claude mcp list` (shows "Connected"). The tools appear in the next session; in a running one, `/mcp` reconnects.

Claude desktop app (Chat): edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then quit and reopen the app:

```json
{
  "mcpServers": {
    "classcad": { "command": "npx", "args": ["-y", "@awv-informatik/classcad-mcp@latest"] }
  }
}
```

The app has no shell PATH. If it cannot start npx, use the absolute path of npx (`which npx`) as `command`; if it then cannot find node, add `"env": { "PATH": "<the folder that holds node>:/usr/bin:/bin" }` to the entry.

Codex, in `~/.codex/config.toml`:

```toml
[mcp_servers.classcad]
command = "npx"
args = ["-y", "@awv-informatik/classcad-mcp@latest"]
```

VS Code (Copilot Chat, agent mode), in `.vscode/mcp.json` or the user MCP config:

```json
{
  "servers": {
    "classcad": { "type": "stdio", "command": "npx", "args": ["-y", "@awv-informatik/classcad-mcp@latest"] }
  }
}
```

Cursor, in `~/.cursor/mcp.json` (Windsurf and most other hosts take the same shape):

```json
{
  "mcpServers": {
    "classcad": { "command": "npx", "args": ["-y", "@awv-informatik/classcad-mcp@latest"] }
  }
}
```

OpenCode, in `opencode.json`:

```json
{
  "mcp": {
    "classcad": { "type": "local", "command": ["npx", "-y", "@awv-informatik/classcad-mcp@latest"] }
  }
}
```

## Sign-in (once per machine)

The MCP works with a free classcad.ch account. The first ClassCAD call on a machine answers "Sign-in required" with a link (`https://classcad.ch/connect?...`). Show that link to the user as a clickable link, then call the `login` tool: it waits and returns as soon as they have signed in (Google, GitHub or email; one click if they already have an account). Then repeat the call. From a terminal, `npx -y @awv-informatik/classcad-mcp@latest login` does the same.

## First test

In a new session, ask for a box. The first time, the sign-in above comes first. Then the agent calls `run_script` and reports a volume. `session_info` should show `"transport": "wasm"`. The first call takes a few seconds longer because the engine assets (about 60 MB) are downloaded once, into `~/.classcad-mcp/wasm/`. After that, the engine starts in about a second and works offline.

## Troubleshooting

- The tools don't appear: the host only loads MCP servers when a session starts. Start a new session or restart the host.
- "npx: command not found" or "node: command not found" in the Claude desktop app: use the absolute path of npx, and the PATH entry described under the app's config.
- Update: nothing to do. `@latest` fetches the newest release whenever the host starts the server; start a new session to pick it up.
- Status of the shared background process: `npx -y @awv-informatik/classcad-mcp@latest status`.
- Details on every setting: https://github.com/awv-informatik/classcad-ai/blob/master/packages/mcp/README.md

## Last resort: build from source

Only when npx cannot fetch the package on this machine (for example, the npm registry is blocked). Choose a lasting location (for example `~/classcad-ai`, not a temp folder), because the host runs the server from there:

```bash
git clone https://github.com/awv-informatik/classcad-ai.git
cd classcad-ai
npm install
npm run build
```

Then, in every config above, replace `npx -y @awv-informatik/classcad-mcp@latest` with `node /abs/path/to/server.js`, where the path is the checkout's `packages/mcp/dist/server.js` (from the repo root, `echo "$PWD/packages/mcp/dist/server.js"` prints it). The terminal commands become `node /abs/path/to/server.js login` and `... status`. To update later: `git pull && npm install && npm run build`.

## Using it

The MCP's own instructions tell the agent how to work: plan the build, fetch the method docs and recipes in one `docs` call, build with a few `run_script` programs, and always verify (mass properties plus `snapshot` renders).

- [MCP README](https://github.com/awv-informatik/classcad-ai/blob/master/packages/mcp/README.md): tools, engines, sessions, and joining a ClassCAD app by invite link
- [Recipes](https://github.com/awv-informatik/classcad-ai/tree/master/packages/skill/recipes): constrained sketching, verification, parametric parts, assembly parameters, patterns, direct modelling
- [ClassCAD documentation](https://classcad.ch/docs/)

## Contact

- Email: info@awv-informatik.ch
- Discord: https://discord.gg/MEbR7xyPMS
- GitHub: https://github.com/awv-informatik/classcad-ai
- AWV Informatik AG: https://awv-informatik.ch/