threecrate-mcp

An MCP server that lets AI agents work with 3D point clouds and meshes using threecrate. Ask your agent to "clean up scan.ply", "align these two scans" or "turn this cloud into a mesh", and it calls these tools.

Works with any MCP client: Claude Code, Claude Desktop, Codex, OpenCode, Cursor, Gemini CLI and others.

Setup

You need uv (for uvx) or Python 3.10+.

Claude Code (from your project folder):

claude mcp add threecrate -- uvx threecrate-mcp

Codex (from your project folder):

codex mcp add threecrate -- uvx threecrate-mcp

OpenCode (opencode.json in your project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "threecrate": { "type": "local", "command": ["uvx", "threecrate-mcp"], "enabled": true }
  }
}

Claude Desktop, Cursor and other apps (their MCP JSON config). These apps don't start servers in your project folder, so pass it with --root:

{
  "mcpServers": {
    "threecrate": {
      "command": "uvx",
      "args": ["threecrate-mcp", "--root", "/path/to/your/scans"]
    }
  }
}

Without uv, install with pip install threecrate-mcp and use threecrate-mcp as the command.

How it behaves

• One workspace folder. Tools only read and write inside it: the folder the server starts in, or --root (also THREECRATE_MCP_ROOT). Paths are relative to it.
• New files, never overwrites. Results go to a new file next to the input (for example scan.downsampled.ply) unless you name one. Inputs are never overwritten, and existing files only with overwrite=true.
• Summaries, not points. Tools return counts, bounds, transforms and errors. Point data stays in files, so a big scan doesn't flood the agent's context.
• Size limit. Clouds above 50 million points are refused (--max-points or THREECRATE_MCP_MAX_POINTS to change).

Tools

Readable point cloud formats: PLY, PCD, XYZ, CSV (and others threecrate supports). Writable: PLY, PCD, XYZ, CSV.

Agent Skill

If you would rather not run a server, the threecrate skill teaches an agent to do the same work with short Python scripts. See INSTALL.md for Claude Code, Codex, Gemini CLI, OpenCode and Cursor.

Development

pip install -e ".[test]"
pytest