# ifcopenshell-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

> **Talk to your BIM models in natural language.**
> An open-source MCP server for IfcOpenShell — query, validate, convert, and compare IFC files through AI agents.

---

## For Architects (no coding required)

### What does this do?

Drag an `.ifc` file into Claude and ask questions like:

> "How many fire doors are on Level 2?"

Claude reads your model and answers:

```
Found 2 IfcDoor elements with FireRating=R60:
- Fire Exit GF (Ground Floor)
- Fire Exit L2 (Level 2)
```

No Revit. No Navisworks. No SQL. Just drag, ask, get answers.

### What can I ask?

| You ask... | It does... |
|-----------|------------|
| "Summarize this model" | Shows project name, total elements, spatial structure |
| "How many walls on Ground Floor?" | Counts and lists them with IDs |
| "Validate that all elements have materials" | QA/QC report: PASS / FAIL / WARNING per element |
| "Extract concrete quantities for Level 1" | Area, volume, length organized by element |
| "What changed since last week's version?" | Diff report: added, removed, modified elements |
| "Convert this to GLB for web viewing" | Creates a 3D file viewable in any browser |

Complete tool list at the bottom of this page.

### How to install (5 minutes, one time only)

**Step 1:** Install **uv** (a tiny installer). Open your terminal once and paste:

**Windows (PowerShell):**
```
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Mac (Terminal):**
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Step 2:** Download this tool. In the same terminal:

```
git clone https://github.com/Daviidro/ifcopenshell-mcp.git
cd ifcopenshell-mcp
uv sync
```

**Step 3:** Tell Claude about it. Open Claude Desktop → Settings → Developer → Edit Config, and paste:

```json
{
  "mcpServers": {
    "ifcopenshell": {
      "command": "uv",
      "args": ["run", "ifcopenshell-mcp"],
      "cwd": "D:/ifcopenshell-mcp"
    }
  }
}
```

Restart Claude Desktop. Done. Drag any `.ifc` file and start asking.

### Is this safe?

**Yes. Your files never leave your computer. Period.**

- Everything runs **100% locally** — no cloud, no accounts, no internet needed
- It only reads IFC files **you explicitly drag into Claude** — nothing else
- It cannot write files outside your project folder
- It cannot access system files
- The code is **open source (MIT)** — anyone can inspect every line
- Built on [IfcOpenShell](https://ifcopenshell.org), trusted by thousands of architects and engineers since 2011

No telemetry. No analytics. No hidden anything.

---

## For Developers (contributing code)

### Tools

| Tool | Description | Example question |
|------|-------------|-----------------|
| `query_ifc_elements` | Search by type, level, or properties | "Show all fire doors" |
| `get_ifc_statistics` | Model overview and class distribution | "Give me a summary" |
| `get_element_properties` | Full properties of one element by GUID | "Details of wall 3GQqVv..." |
| `list_ifc_spaces` | All rooms/spaces | "List all rooms" |
| `validate_ifc_model` | QA/QC: materials, properties, containment, naming | "Validate this model" |
| `compare_ifc_models` | Diff between two IFC versions | "What changed?" |
| `extract_ifc_quantities` | Quantity takeoffs (markdown/CSV/JSON) | "Concrete volume?" |
| `convert_ifc_to_gltf` | IFC to GLB for web visualization | "Make it viewable online" |

### Supported formats
- IFC2x3, IFC4, IFC4.3 (`.ifc`, `.ifczip`, `.ifcxml`)
- Output: markdown, CSV, JSON
- GLB: requires IFC files with geometric representations. Semantic-only IFCs report conversion failure.

### Setup

```bash
git clone https://github.com/Daviidro/ifcopenshell-mcp.git
cd ifcopenshell-mcp
uv sync
uv run pytest tests/ -v    # 19 tests, all must pass
```

### Tests

```bash
uv run pytest tests/ -v
# Expected: 19 passed (13 functional + 6 error handling)
```

### Roadmap
- [ ] Clash detection (bounding box)
- [ ] COBie spreadsheet export
- [ ] IFC to Revit roundtrip via Speckle
- [ ] Classification system validation (Uniclass, OmniClass)

### Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Built on [IfcOpenShell](https://github.com/IfcOpenShell/IfcOpenShell) (LGPL-3.0) and [MCP](https://modelcontextprotocol.io/). Also check out the [official IfcOpenShell MCP](https://docs.ifcopenshell.org/ifcmcp.html).

### Ecosystem

- [speckle-mcp](https://github.com/Daviidro/speckle-mcp) — AEC interoperability
- [bim-agent](https://github.com/Daviidro/bim-agent) — Multi-MCP orchestrator
- [awesome-aec-mcp](https://github.com/Daviidro/awesome-aec-mcp) — Curated MCP list

## License

MIT — see [LICENSE](LICENSE) file.