# Ladybug Tools MCP

[English](README.md) | [简体中文](README.zh-CN.md)

## Overview

Ladybug Tools MCP is an MCP service built with FastMCP for agent applications.
Through natural-language conversation, users can use the core capabilities of Ladybug Tools for common workflows including modeling, editing, querying, simulation, and data visualization, and can do so without depending on a CAD interface.

![Opencode Honeybee Modeling Flow](https://raw.githubusercontent.com/LoftyTao/ladybug-tools-mcp/f530e12d9836db518b187639eee4e7644a6a7e9f/resources/remotion/snapshots/videos/opencode-honeybee-modeling-vtkjs-flow-en/opencode-honeybee-modeling-vtkjs-flow-en-latest.gif)

## Contents

- [Overview](#overview)
- [User Groups](#user-groups)
- [Core Concepts](#core-concepts)
- [Quick Start](#quick-start)
- [Web View Mode](#web-view-mode)
- [First Use](#first-use)
- [Workflow Examples](#workflow-examples)
- [How to Contribute](#how-to-contribute)
- [Todo](#todo)
- [Acknowledgements](#acknowledgements)
- [Open Source License](#open-source-license)
- [Contact](#contact)

## User Groups

The original purpose of Ladybug Tools MCP is to turn design or technical concepts into concrete outputs quickly.
For example, when a professor explains “What is a Trombe wall?” in a building technology course, a student can open Codex voice mode during the lecture, and by the time the explanation is finished, Codex can already transform the concept into inspectable models and files, together with graphical workflow output.

For that reason, the main target users are students and teachers, followed by building professionals and senior engineers.
They may want an agent to take over some tedious work, while still keeping the final choice for most tasks in their own hands.
For users who do not know much about 3D software workflows, Ladybug Tools MCP can also serve as a way to experience the Ladybug Tools ecosystem.

## Core Concepts

Ladybug Tools MCP is different from Ladybug Tools as used inside Rhino / Grasshopper.
To use it well, it helps to understand several core concepts of this project, including MCP, agents, skills, tokens, Garden, and Flowerpot.

### Model Context Protocol

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open standard used to connect external systems to agent applications.
For most users, Ladybug Tools provides a user interface for human interaction inside Rhino / Grasshopper.
Ladybug Tools MCP, by contrast, is a toolbox that an agent can call through natural language.
It packages the core capabilities of the Ladybug Tools Core SDK into a standardized set of tools and usage guidance, and exposes them through MCP so that agent applications can call them.

### Agent

An [Agent](https://openai.github.io/openai-agents-python/agents/) is a large language model with instructions and tools.
Ladybug Tools MCP is usually called as a toolset from inside an agent application.

### Agent Skills

[Skills](https://agentskills.io/home) are a practical way to turn prompt engineering into reusable operating guidance.
By summarizing domain knowledge and workflows in Markdown, they provide an “instruction manual” that helps an agent follow your intent more reliably.

### Tokens

Tokens are the unit used to calculate cost in agent applications.
Models differ in performance, speed, and token pricing, but I still recommend using the best and most cost-effective model you can reasonably access if you want a good Ladybug Tools MCP experience.

Long modeling and simulation workflows benefit from a large context window.
Usage and cost depend on the model, client, and task.

### Garden

A Garden is the local path used to store and manage everything generated by Ladybug Tools MCP. The main outputs inside it are tracked through Git.

Because agent applications can easily do things beyond expectation in real work, a large part of this project has been about constraining the agent’s attention inside the Garden.
This has been one of the main successful lessons from several months of development practice.

### Flowerpot

Flowerpot is the intermediary layer used by Ladybug Tools MCP to exchange information with other non-agent interfaces.
For example, the Flowerpot components we developed for Ladybug Tools mainly act as relay plugins inside the ecosystem, with the goal of helping users complete the necessary manual work.

Because we want users to keep as much attention as possible on the interaction with the agent, instead of returning to manual production steps, we have not tried to build separate platform UIs for Ladybug Tools MCP. Instead, we recommend that you make good use of existing Ladybug Tools infrastructure and then pass data and information through Flowerpot.

## Quick Start

### Prerequisites

Before using Ladybug Tools MCP, some system prerequisites usually need to be configured.
At minimum, that often includes:

- Python 3.12
- Ladybug Tools runtime matching the current `v1.2.0` matrix below
- Git
- uv
- Any agent application, such as [Codex](https://chatgpt.com/codex), [Claude Code](https://code.claude.com/docs/en/desktop-quickstart), [Open Code](https://opencode.ai/), or [OpenClaw](https://openclaw.ai/)

If you are not familiar with agent applications, I am very happy to recommend [Codex](https://chatgpt.com/codex).

The table below records the external runtime versions expected by Ladybug Tools MCP `v1.2.0`. Install the engines needed for your workflows.
Ironbug authoring uses the project-local Python layer.

Ladybug Tools MCP | Python | Radiance | OpenStudio SDK | EnergyPlus | OpenStudio App | URBANopt CLI | THERM |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `v1.2.0` | 3.12 | [5.4 (2023-11-05)](https://github.com/LBNL-ETA/Radiance/releases/tag/rad5R4) | [3.11.0](https://github.com/NatLabRockies/OpenStudio/releases/tag/v3.11.0) | 25.1.0 | [1.11.1](https://github.com/openstudiocoalition/OpenStudioApplication/releases/tag/v1.11.1) | [1.4.0](https://github.com/urbanopt/urbanopt-cli/releases/tag/v1.4.0.rc1) | [8.1.30 beta](https://windows-downloads.lbl.gov/software/therm/THERM8_1_30_SetupFull.exe) |

Use `LB_get_runtime_config` to check installed engines and obtain setup guidance for any missing runtime.

### Installation Guide

If you do not really know what MCP is and do not want to do the setup manually, you can hand this job over to [Codex](https://chatgpt.com/codex) or another agent application.

Using Codex as an example, you only need to:

- Install Codex.
- Open a local workspace.
- Send this project link to Codex.
- Say:

```text
Help me install and configure the MCP from this project into this workspace.
```

#### Local Installation Commands

Run the following commands in the target workspace.
Replace `<repo-url>` with the repository URL of this project and `<repo-dir>` with the cloned folder name.

Windows PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version
```

macOS / Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version
```

Then run the following on all systems:

```bash
git clone <repo-url>
cd <repo-dir>
uv venv --python 3.12 .venv
uv pip install -r requirements.txt
uv pip install -e .
uv run --no-project python -c "import ladybug_tools_mcp; print(ladybug_tools_mcp.__version__)"
```

`requirements.txt` pins the dependencies for a reproducible installation.

#### MCP Configuration Examples

Replace `<absolute-repo-path>` with the absolute path of this repository on your machine, and replace `<python-command>` with the Python executable inside this project’s virtual environment.

Windows:

```text
<absolute-repo-path>\.venv\Scripts\python.exe
```

macOS / Linux:

```text
<absolute-repo-path>/.venv/bin/python
```

Codex uses TOML:

```toml
[mcp_servers.ladybug-tools-mcp]
command = "<python-command>"
args = ["-m", "ladybug_tools_mcp.server"]
cwd = "<absolute-repo-path>"
```

Cursor, OpenCode, or other agent applications that use `mcpServers` can use JSON:

```json
{
  "mcpServers": {
    "ladybug-tools-mcp": {
      "command": "<python-command>",
      "args": ["-m", "ladybug_tools_mcp.server"],
      "cwd": "<absolute-repo-path>"
    }
  }
}
```

Claude Code is recommended to add the local stdio MCP through the CLI:

```text
claude mcp add ladybug-tools-mcp -- "<python-command>" -m ladybug_tools_mcp.server
```

If you need project-level shared configuration, you can use:

```text
claude mcp add ladybug-tools-mcp --scope project -- "<python-command>" -m ladybug_tools_mcp.server
```

Claude Code project-level `.mcp.json` files also use the `mcpServers` structure:

```json
{
  "mcpServers": {
    "ladybug-tools-mcp": {
      "command": "<python-command>",
      "args": ["-m", "ladybug_tools_mcp.server"],
      "env": {}
    }
  }
}
```

OpenClaw uses `mcp.servers` in its MCP client registry:

```json
{
  "mcp": {
    "servers": {
      "ladybug-tools-mcp": {
        "command": "<python-command>",
        "args": ["-m", "ladybug_tools_mcp.server"],
        "cwd": "<absolute-repo-path>"
      }
    }
  }
}
```

After configuration is finished, restart the agent application and confirm that the MCP server is connected.

#### Grasshopper Component Path

For Grasshopper integration, use the [component source in the development repository](https://github.com/LoftyTao/rec-ladybug-tools-mcp/tree/main/src/grasshopper_components).
In this subsection, `<absolute-repo-path>` refers to that development checkout, which Grasshopper needs to locate.

It is recommended to set an environment variable first:

Windows PowerShell:

```powershell
[Environment]::SetEnvironmentVariable("LADYBUG_TOOLS_MCP_ROOT", "<absolute-repo-path>", "User")
```

macOS / Linux:

```bash
export LADYBUG_TOOLS_MCP_ROOT="<absolute-repo-path>"
```

If you need to copy the component scripts to another machine or deliver them independently, also check and modify `_DEVELOPMENT_SRC_ROOT` near the top of each `FP *.py` file.
On Windows it should point to:

```text
<absolute-repo-path>\src
```

On macOS / Linux it should point to:

```text
<absolute-repo-path>/src
```

These components add that path into `sys.path` at startup so they can load `flowerpot.runtime` and the Grasshopper collaboration code inside the project.

## Web View Mode

Web View Mode provides a local vtk.js preview for live modeling sessions.
It lets a host application render the current Garden preview through vtk.js while an agent creates or edits Honeybee, Dragonfly, Fairyfly, or VisualizationSet outputs.

The viewer runs locally at `127.0.0.1`. Open the returned URL in your client’s browser or sidebar to follow changes to the current Garden.

### Enable

Ask the agent to enable Web View Mode before modeling or editing:

```text
Enable Web View Mode for this Garden, then create or edit the Honeybee model.
```

Through MCP Code Mode, the agent calls:

```text
GD_web_view_start_mode(garden_root, name="...")
```

Starting the mode creates a Garden-local session and returns its local `viewer.url`, for example:

```text
http://127.0.0.1:3127
```

Open the returned `viewer.url` to display the preview.

### Close

Ask the agent to stop Web View Mode, or call:

```text
GD_web_view_stop_mode(garden_root)
```

This disables future automatic previews and stops the matching local fallback viewer if one was started.
Preview history under `tmp/web_view/` is preserved.

### Difference From Ordinary Mode

In ordinary mode, modeling tools write Garden files and return compact targets, summaries, and receipts.
No viewer server is started, and no automatic preview file is exported after every edit.

In Web View Mode, significant Honeybee, Dragonfly, Fairyfly, and VisualizationSet operations automatically export session-managed `.vtkjs` previews under:

```text
<garden>/tmp/web_view/previews/
```

The viewer polls Garden session state and reloads the latest `.vtkjs` package without a manual refresh.
These automatic previews are local session state, not formal user-requested Garden artifacts.
If you need a durable reusable artifact, still ask the agent to export a VisualizationSet with `LB_set_to_vtkjs`.

The fallback viewer intentionally uses an explicit local port.
If the requested port is already occupied, startup fails clearly instead of silently choosing another port or leaving the browser pointed at an older Garden.

## First Use

After the MCP server is configured in your agent application, start a new thread and ask it to use Ladybug Tools MCP. In Codex, the most direct path is to configure the server in `~/.codex/config.toml` with the TOML example above, restart Codex, then describe the Garden or modeling task directly.

If your host supports skills, invoke the `ladybug-tools-mcp-use` skill with `/`, then input `HI , Ladybug Tools !` to activate the onboarding flow for the three main usage intents that we provide.
After the onboarding is complete, you can start building according to your intent.

![Welcome Flow](https://raw.githubusercontent.com/LoftyTao/ladybug-tools-mcp/f530e12d9836db518b187639eee4e7644a6a7e9f/resources/remotion/snapshots/videos/opencode-onboarding-flows/welcome-fixed-3-options-en-latest.gif)

In general, the agent application will output the onboarding template according to the guidance in our skills, but the actual result still depends on the host application’s instructions and the base capability of the language model.
I strongly recommend that you use the best model available within your means in order to use our tools more effectively.

## Workflow Examples

In our cross-testing set, we have successfully made agent applications complete the following kinds of work.
The stability and token cost of these workflows have become relatively steady, and I believe they are a good place to begin learning.

### Build a small model from a blank project

- Create a new Garden.
- Create a Honeybee Model.
- Create one or two Rooms.
- Add windows, doors, and shades to exterior walls.
- Check whether the model has missing faces, broken adjacencies, or boundary-condition issues.

### Continue editing an existing model

- Find the specified room, wall, window, or door.
- Modify the location, dimensions, and construction of windows.
- Add low-U-value windows, heavy wall constructions, occupant loads, and equipment loads.
- Assign program types, setpoints, and a simple HVAC system to rooms.
- Re-check the model after editing.

### Building performance simulation workflow

- Search for and download the EPW weather file for a specified city.
- Save the weather file into the Garden.
- Start an Energy simulation.
- Read EUI, error information, and some hourly results.
- Export the results as monthly charts, hourly charts, or HTML pages.

### Prepare reusable Energy resources

- Create schedules, program types, construction sets, setpoints, and HVAC templates.
- Save them into the Garden Properties Library.
- Search for and reuse these resources in later models.
- For incomplete sources, record only what can be determined and do not invent material layers or window parameters.

### Author custom HVAC with Ironbug

- Create Ironbug DetailedHVAC objects for coils, fans, pumps, boilers, chillers, terminals, plant loops, air loops, setpoint managers, and output requests.
- Assemble source-backed custom HVAC systems such as PTAC, PTHP, FCU, DOAS, VAV, VRF, boiler reheat, chiller plant, and condenser-water loop cases.
- Link Ironbug ThermalZone objects to Honeybee or Dragonfly rooms, then apply the DetailedHVAC model before running the standard Energy simulation workflow.
- Use the Ironbug workflow when an HVAC Template is too coarse and you need object-level loop topology, child components, and OpenStudio / EnergyPlus-facing equipment intent.

### Do basic Radiance work

- Create skies, WEA files, sky matrices, sensor grids, and views.
- Assign Radiance modifiers to model objects.
- Start grid or view simulations.
- Read HDR, falsecolor, GIF, or annual daylight metrics.
- Convert the results into inspectable visualization sets.

### Connect Grasshopper and the agent

- Use Flowerpot components in Grasshopper to hand over the current model or project context.
- Let the agent continue modeling, editing, saving, and validating in the Garden.
- Let the Grasshopper side continue to handle manual selection, preview, and the necessary manual operations.
- This is suitable for a workflow where geometry is handled in the interface and organization plus long-chain tool use is handled by the agent.

### Preserve and restore project state

- Create a Garden Version before important operations.
- Try modifying the model or simulation resources.
- If the result is unsatisfactory, restore to the earlier version.
- After restoration, continue exporting HTML / SVG and other inspection outputs.

## How to Contribute

Because this project is built to a very large extent through agent-assisted development, I do not reject contributions made with agent applications.
However, there are several principles that need to be followed so that the project does not grow in an uncontrolled way.

- [Ladybug Tools Core SDK](https://discourse.ladybug.tools/pub/ladybug-tools-core-sdk-documentation) is the core of all MCP tools in this project.
If the tool you want to add is not within the scope of the SDK, then this project should not be the place for the follow-up implementation.
In that case, it is more appropriate to contribute directly to the Ladybug Tools project itself.
- All new tool development should first go through an open GitHub Issue discussion, and the discussion content and development plan should be led by humans.
- Only write code that solves the current problem.
If an AI code review points out issues that you have not actually encountered in normal usage scenarios, then we should not handle those issues.
- Better to have too few tools than too many; do not add entities unless they are truly necessary.
- If these principles can be followed, I would be very happy for you to join this community-driven maintainer group.

## Todo

These are the main directions for later development.
Before there is a broad user signal telling us otherwise, the project will continue to expand in these directions.

- [x] Dragonfly Model creation and editing tools
- [x] Add URBANopt support
- [ ] More Visualization Set pre-processing and post-processing support
- [ ] Expand retained Ironbug Energy acceptance cases for more custom HVAC topologies
- [ ] Web View and Model Editor tools for direct agent collaboration
- [ ] A demo mode that can visualize all processes and steps
- [ ] Cloud service support
- [ ] ...

## Acknowledgements

Special thanks to the [Ladybug Tools community](https://discourse.ladybug.tools/) and the [Ladybug Tools team](https://www.ladybug.tools/about.html#team):

- **Mostapha** [raised the priority of Pydantic compatibility](https://discourse.ladybug.tools/t/upgrade-to-pydantic-2-0/36437/9), which greatly reduced the development difficulty of this project.
- **Chris** helped make the `.svg` format of [Visualization Set](https://discourse.ladybug.tools/t/bug-of-dumpvisset-or-incomplete-known-issues/39972) the main model visualization scheme for the MCP workflow, which made it possible for us to fully inspect built content without relying on a CAD interface.

Beyond that, the implementation core of this project remains the [Ladybug Tools Core SDK](https://discourse.ladybug.tools/pub/ladybug-tools-core-sdk-documentation), which is the result of many years of development by the Ladybug Tools team.

## Open Source License

Ladybug Tools MCP is released under the GNU General Public License Version 3 (GPL v3), consistent with the open source license used by the Ladybug Tools project.

## Contact

You can contact me through the following methods:

- Email: `loftytao@foxmail.com`
- WeChat: `LoftyTao`

If someone can offer some Codex or Claude Code tokens, or even a subscription plan, that would be even better.
I would really appreciate that kind of support.