topopt

topopt

Install | Use | Examples | Documentation | License

It gives your AI agent a topology optimizer that sets itself up and runs on your own computer. The start part can be an STL file you already have, a sketch, a description in words, or a shape you work out with the agent in the chat: the rough form, where it is mounted and where the loads go, checked in a picture and changed until it is right. Then topopt runs the topology optimization: it finds a light shape that carries those loads and writes a smooth STL file that you can print.

More on the website: topopt.ai

Three ways to start a part:

• An STL file that you have. "Here is bracket.stl. Keep the two screw holes, the tip carries 5 kg. Make it lighter."

• A sketch and a few words. "I'm building a bike frame with 3D-printed lugs. Can the head tube lug be topology optimized?" With a sketch like this one:

• Words only. "A wall hook for a T-shirt, two screws, 2 kg." Or a footbridge on two supports, or a stool that holds 100 kg.

A footbridge on two supports: a recorded run (200 passes, 39 minutes with gpu-mg on an integrated GPU) in the dashboard replay.

Install

topopt works with any agent client that supports MCP servers. We test it most with Claude and recommend it, but topopt is not tied to Claude. topopt runs on a Mac with Apple silicon or on Linux x86_64, with at least 16 GB of memory for the example. You need no tool first: topopt uses your uv if you have one (uv 0.6.8 or newer); else the setup downloads a pinned uv release and checks its checksum.

What the setup downloads, and what topopt sends

• uv 0.13.5, only if topopt finds no uv that it can use (18 MB, checked by its SHA256). Python 3.13 through uv (35 MB), the 55 packages of requirements.lock from PyPI, and setuptools (the setup builds the topopt code with it): about 200 MB in all, about 700 MB on disk. The sizes are from Linux x86_64.
• After a plugin update, a complete setup links the code again offline. It downloads only when the lock file changed, and once when the Python of the launcher changes (the update to Python 3.13 downloads Python 3.13 and the packages again, about 180 MB, and needs the network).
• topopt sends no data unless you allow it to send diagnostic data. A run, the dashboard server (127.0.0.1 only), the tools and the pages that open in your browser connect to nothing outside your computer, and they work offline.
• The details, and how we checked them: What the setup downloads.

Clients

Claude Desktop is the most tested client and the one we recommend: the chat shows the pictures that topopt makes of your part.

1. Download topopt.mcpb from the newest release (v0.5.1).
2. Open the file with Claude Desktop.
3. In a new chat, ask for the first example: "Run the topopt example examples/hook/hook.yaml and give me the dashboard link."

The first start sets up Python in the background: 1 to 3 minutes. Until then, the chat marks a topopt call as Failed: that is the setup status, not a fault. Everything else (the skills for the chat, the work folder field, problems): Claude Desktop.

The Code tab of Claude Desktop uses the Claude Code plugin: see Claude Code below.

This repo is a Claude Code plugin and also its marketplace. #latest is the newest release. In a terminal:

claude plugin marketplace add chartergroup/topopt#latest
claude plugin install topopt@topopt

Or in a Claude Code session:

/plugin marketplace add chartergroup/topopt#latest
/plugin install topopt@topopt

Then start Claude Code in your work folder and type:

/topopt:start-here

Claude checks the machine, helps you describe the part, checks the problem, starts the run and gives you the dashboard link (usually http://127.0.0.1:8765/). The first start sets up Python for the plugin: 1 to 3 minutes, about 200 MB (what it downloads). Until then, a topopt tool answers with the setup status.

In the Code tab of Claude Desktop, the plugin command opens Settings > Plugins. Add the plugin there:

1. Open Settings > Plugins. Press + Add, choose Add marketplace, then Add from a repository.
2. Type chartergroup/topopt#latest in the field URL and press Sync.
3. Right after the sync, press Add on topopt: topology optimization for 3D printing. In the dialog about local MCP servers, press Continue.
4. Start a session in a project folder and ask for the first example.

More: The Code tab: the plugin.

To update an install from #latest, run these in a terminal, then start a new session:

claude plugin marketplace update topopt
claude plugin update topopt@topopt

A pinned install updates another way: Update. Pinned releases, a checkout and first-run problems: Install the Claude Code plugin.

Every client starts the same server. Get a checkout and set it up once:

git clone https://github.com/chartergroup/topopt
cd topopt
sh scripts/topopt-env.sh sync

Then add the server to the MCP config of your client, with full paths (VS Code names the top key servers; Gemini CLI has no key type):

{
  "mcpServers": {
    "topopt-local": {
      "type": "stdio",
      "command": "sh",
      "args": ["/full/path/to/topopt/scripts/topopt-env.sh", "mcp"],
      "env": { "TOPOPT_WORKSPACE": "/full/path/to/topopt" }
    }
  }
}

If the tools do not show, run this in the checkout (about 2.5 s on Linux x86_64; it prints progress lines):

sh scripts/topopt-env.sh doctor

The setup, a JSON and a TOML config template, and the typical problems: the guide for any MCP client.

Other clients

For each client below, set up a checkout as in "Generic MCP client". The client facts have the dates.

Open the topopt folder in Cursor and enable the topopt MCP server of .cursor/mcp.json. In the one Mac test (2026-10-27) this server stayed Disabled, and a user entry in ~/.cursor/mcp.json worked (the entry).

Start codex in the topopt folder and trust the project when Codex asks. The project file .codex/config.toml starts the server. More: Codex CLI.

Put this in .vscode/mcp.json of the topopt folder, open the folder in VS Code and trust the workspace:

{
  "servers": {
    "topopt": {
      "type": "stdio",
      "command": "sh",
      "args": ["${workspaceFolder}/scripts/topopt-env.sh", "mcp"],
      "env": { "TOPOPT_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

More: VS Code agent mode.

Put this in .gemini/settings.json of the topopt folder, start gemini there and trust the folder:

{
  "mcpServers": {
    "topopt": { "command": "sh", "args": ["scripts/topopt-env.sh", "mcp"] }
  }
}

More: Gemini CLI.

Use

With an agent client, ask in words. You can:

• Bring or describe the part. One YAML file and one STL file for each region; the agent can write them from your words (The YAML format).
• Check it. topopt check gives the grid size and a time estimate, and starts no run (Run a problem).
• Run it and watch. The dashboard shows the shape, the volume and the compliance while the run goes (The dashboard). A recorded run plays again with --replay (Replay).
• Run a fine pass. A finer voxel from the design of a finished run (Fine pass).
• Check the print and the stress. Print checks and Verify the result.
• Get the STL and the numbers. result/final.stl and result/metrics.json: mass, stiffness and run time (The final mesh).
• Get pictures. Render.

In a client that shows MCP Apps, for example Claude Desktop, ask the agent to show the part in 3D: the chat shows the design space, the regions, an arrow for each load and the time estimate (the tool show_problem, see MCP server and its tools). The button "Start the run" in that view starts the run; the view then shows the pass and the volume every 5 seconds, and at the end a button "Discuss the result" gives the chat a message about the result (the host may put it into the chat input for you to send).

The hook: a full block of the design space would weigh 85.6 g. The part weighs 25.4 g (70 % less). The run took 133 s with gpu-mg on an integrated GPU.

Examples. The gallery shows each example part with a picture, the run and the mass. To run one, ask your agent, or in a checkout after Install: topopt run examples/hook/hook.yaml --out runs/hook.

Change a part with words. The hook prompt guide shows four prompts that change the hook example: two hooks at an angle on one base, three screws, a 2 kg jacket in place of a T-shirt, and a lighter part. Each prompt has its picture, the mass and the files to run it again.

The work folder is where topopt keeps your runs (runs/<name>/). How to change it for each client: The work folder.

Documentation

• The reference pages:
  • Install, platforms and your machine
  • Run a problem
  • The dashboard, the MCP server and the render
  • Print checks, the STEP file and the tet mesher
  • Verify the result, ratchet and cleanup
  • Run topopt in any MCP client
  • Fine pass
  • Tests, acceptance and limits
• Client facts, with dates.
• CONTRACTS.md: the final spec: the YAML schema, the CLI, the snapshot format.
• MCP server and its tools.
• The example gallery and the hook example.
• How the pictures of this page were made, and the recorded hook run for a replay of the dashboard.
• Releases and the changelog.
• Test an install in a client and report back.

License

topopt is under the MIT license: see LICENSE. Third-party notices list the license of every package that topopt installs and of the third-party files in this repository.

Contributing

We recommend contributing with a coding agent. The instructions for agents are already in this repository, so open the folder in your agent and it finds what it needs by itself.

To contribute by hand, or to see the whole process (an issue first, a branch, a review by someone else, a person merges), read the contributing guide.