Ladybug Tools
Enables natural-language interaction with Ladybug Tools for building performance simulation, 3D modeling, and data visualization, allowing agents to perform complex environmental analysis tasks without CAD software.
What is Ladybug Tools?
Ladybug Tools is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enables natural-language interaction with ladybug tools for building performance simulation, 3d modeling, and data visualization, allowing agents to perform complex environmental analysis tasks withou...
Enables natural-language interaction with Ladybug Tools for building performance simulation, 3D modeling, and data visualization, allowing agents to perform complex environmental analysis tasks without CAD software.
This server falls under the Data Science & ML category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enables natural-language interaction with Ladybug Tools for
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx ladybug-toolsConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Ladybug Tools
Ladybug Tools MCP Server bridges AI agents with the Ladybug Tools ecosystem for building performance simulation and environmental analysis. It enables natural-language control over energy simulation, daylight analysis, 3D geometry creation, and results visualization — letting architects and engineers run Honeybee and Radiance workflows without manual CAD software interaction.
Prerequisites
- Python 3.12 specifically (required by the package)
- uv package manager installed (https://astral.sh/uv)
- Git for cloning the repository
- Ladybug Tools and its simulation dependencies (Honeybee, Radiance, EnergyPlus) installed if you intend to run actual simulations
- An MCP-compatible client such as Claude Code or Cursor
Install uv
uv is required to manage the Python 3.12 environment and run the server. Install it for your platform.
# macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Clone the repository
Clone ladybug-tools-mcp to a permanent directory. The absolute path will be needed in the configuration.
git clone https://github.com/LoftyTao/ladybug-tools-mcp.git
cd ladybug-tools-mcpCreate a Python 3.12 environment and install dependencies
Use uv to create an isolated Python 3.12 virtual environment and install all required packages.
uv venv --python 3.12 .venv
uv pip install -r requirements.txt
uv pip install -e .
# Verify the install:
uv run python -c "import ladybug_tools_mcp; print(ladybug_tools_mcp.__version__)"Set the required environment variable
LADYBUG_TOOLS_MCP_ROOT must point to the absolute path of the cloned repository. Add it to your shell profile for persistence.
# macOS / Linux:
export LADYBUG_TOOLS_MCP_ROOT="/path/to/ladybug-tools-mcp"
# Windows PowerShell:
[Environment]::SetEnvironmentVariable("LADYBUG_TOOLS_MCP_ROOT", "C:\path\to\ladybug-tools-mcp", "User")Add to Claude Code
Register the server with Claude Code using the Python interpreter from the uv virtual environment.
claude mcp add ladybug-tools-mcp -- "/path/to/ladybug-tools-mcp/.venv/bin/python" -m ladybug_tools_mcp.serverAlternative: Cursor / JSON configuration
For Cursor or other JSON-based MCP clients, add the server configuration manually.
{
"mcpServers": {
"ladybug-tools-mcp": {
"command": "/path/to/ladybug-tools-mcp/.venv/bin/python",
"args": ["-m", "ladybug_tools_mcp.server"],
"cwd": "/path/to/ladybug-tools-mcp"
}
}
}Ladybug Tools Examples
Client configuration
Cursor mcp.json configuration for Ladybug Tools MCP Server using the uv virtual environment Python.
{
"mcpServers": {
"ladybug-tools-mcp": {
"command": "/Users/yourname/ladybug-tools-mcp/.venv/bin/python",
"args": ["-m", "ladybug_tools_mcp.server"],
"cwd": "/Users/yourname/ladybug-tools-mcp"
}
}
}Prompts to try
Example natural-language prompts for building performance simulation tasks.
- "Create a simple shoebox room model 10m x 8m x 3m and run an energy simulation for climate zone 5A."
- "Set up a daylight analysis for the model using Radiance and report the spatial daylight autonomy."
- "Add a window-to-wall ratio of 40% to the south facade and re-run the energy model."
- "Visualize the annual solar radiation on the roof surface and export the results as a colored mesh."
- "What HVAC system is currently assigned to the model and what are its COP values?"Troubleshooting Ladybug Tools
Import error for ladybug or honeybee packages on server start
The Ladybug Tools Python libraries must be installed in the same virtual environment. Run 'uv pip install ladybug-core honeybee-core' inside the repo directory, or ensure you installed the full requirements.txt which should pull these in.
LADYBUG_TOOLS_MCP_ROOT not set error
The server requires this environment variable to locate its resources. Add it to your shell profile (~/.zshrc or ~/.bashrc) and restart your terminal, or set it directly in the MCP client configuration's env block.
Simulation tools fail with EnergyPlus or Radiance not found
Ladybug Tools requires the simulation engines to be installed separately. Install OpenStudio/EnergyPlus from https://energyplus.net and Radiance from https://github.com/LBNL-ETA/Radiance/releases. Ensure their executables are on the system PATH.
Frequently Asked Questions about Ladybug Tools
What is Ladybug Tools?
Ladybug Tools is a Model Context Protocol (MCP) server that enables natural-language interaction with ladybug tools for building performance simulation, 3d modeling, and data visualization, allowing agents to perform complex environmental analysis tasks without cad software. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Ladybug Tools?
Follow the installation instructions on the Ladybug Tools GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Ladybug Tools?
Ladybug Tools works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Ladybug Tools free to use?
Yes, Ladybug Tools is open source and available under the GPL 3.0 license. You can use it freely in both personal and commercial projects.
Ladybug Tools Alternatives — Similar Data Science & ML Servers
Looking for alternatives to Ladybug Tools? Here are other popular data science & ml servers you can use with Claude, Cursor, and VS Code.
Ultrarag
★ 5.6kA Low-Code MCP Framework for Building Complex and Innovative RAG Pipelines
RocketRide
★ 3.1k📇 🏠 - MCP server that exposes RocketRide AI pipelines as t
Aix Db
★ 2.1kAix-DB 基于 LangChain/LangGraph 框架，结合 MCP Skills 多智能体协作架构，实现自然语言到数据洞察的端到端转换。
NeMo Data Designer
★ 1.9k🎨 NeMo Data Designer: Generate high-quality synthetic data from scratch or from seed data.
PaperBanana
★ 1.7kOpen source implementation and extension of Google Research’s PaperBanana for automated academic figures, diagrams, and research visuals, expanded to new domains like slide generation.
MiniMax
★ 1.5kBridges MiniMax AI capabilities to the Model Context Protocol, enabling AI agents to perform image understanding, text-to-image generation, and speech synthesis. It provides a standardized interface for accessing MiniMax's core tools via JSON-RPC.
Browse More Data Science & ML MCP Servers
Explore all data science & ml servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Ladybug Tools in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Ladybug Tools?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.