IFCX MCP

A Model Context Protocol server for creating IFC5 / IFCX building information models through AI assistants.

You don't interact with this server directly. You connect it to an MCP client such as Claude Code, Claude Desktop, or any other MCP-compatible client, and then use natural language to author BIM models.

The project targets the IFCX examples and tooling style used in the IFC5 development work: alpha JSON .ifcx, post-alpha tiered index.ifcx with NDJSON tables, and zipped post-alpha .ifcx packages.

What It Can Do

The server keeps IFCX drafts in memory while it is running. A client can then drive the model through a normal authoring flow:

1. Create a model with standard IFCX imports and provenance.

2. Add Project > Site > Building > Storey > Space.

3. Create reusable type nodes, such as wall, window, and pipe segment types.

4. Create element occurrences and attach them to the spatial tree.

5. Instantiate occurrences from types.

6. Attach mesh, BRep, curve, and procedural geometry hints.

7. Use richer authoring factories for walls from axes, windows with voids, pipe networks with ports, and storey grids.

8. Add material, PBR material data, current IFC5 standard properties, classifications, bSDD references, and georeferencing.

9. Create patch layers and explain their effect.

10. Validate references, cycles, mesh indices, IFClite IFCX parsing, and IDS rules.

11. Preview a viewer-shaped tree and export glTF / Three.js preview artifacts.

12. Write alpha JSON, tiered IFCX, or zipped post-alpha IFCX.

13. Dry-run or perform a layer-version publish to an IFCX layer API.

Related MCP server: OpenStudio MCP Server

Install

git clone https://github.com/louistrue/ifcx-mcp.git
cd ifcx-mcp
npm install
npm run build

MCP Client Configuration

Add the server to your MCP client using stdio transport. Change the path to wherever you cloned the repository.

Claude Code (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "ifcx": {
      "command": "node",
      "args": ["/path/to/ifcx-mcp/dist/server.js"]
    }
  }
}

Claude Desktop (claude_desktop_config.json): same format.

The server starts automatically when the MCP client launches.

For local development without an MCP client:

npm run dev

Usage Guide

Once the server is connected to your MCP client, you author models through natural language. The AI assistant translates your requests into the appropriate tool calls.

Creating a Model

"Create an IFCX model called Campus"

Initializes an in-memory draft with standard IFC imports and provenance tracking.

Building Spatial Structure

"Add a project with a site, a building called HQ, and two storeys: Ground Floor at 0m and First Floor at 3.5m"

Creates the full IfcProject > IfcSite > IfcBuilding > IfcBuildingStorey hierarchy.

Adding Elements

"Create a concrete wall type with 200mm thickness, then place exterior walls around a 20x12m rectangle on the ground floor"

You can work at different levels of detail:

• Low-level — create a type, then elements, then attach geometry separately.

• Rich factories — create walls from axis lines, windows with automatic void cutting, pipe networks with distribution ports, or storey grids, all in one step.

Attaching Geometry

Four geometry representations are supported:

• Mesh — vertices and face indices (triangulated surfaces).

• Procedural — extrude, sweep, revolve, or boolean hints.

• BRep — OCCT BREP or STEP AP242 payloads.

• Curves — polylines, arcs, circles, B-splines, or composite curves.

Adding Metadata

"Classify all walls as Uniclass Ss_25_10_30 and resolve via bSDD"

• Materials with optional PBR data (roughness, metalness, color).

• Classifications (CCI, NL-SfB, Uniclass) with live bSDD resolution.

• Georeferencing via EPSG codes or WKT.

• Patch layers for delta/change tracking over a base model.

Validating

"Validate my model"

Runs a multi-stage pipeline: schema validation, composition checks, reference integrity, geometry sanity, and adapter-level IFClite/IFCX-core checks. You can also run IDS validation and convert issues into BCF topics.

For export checks, use ifcx_validate_ifc5_compliance. That tool validates the sanitized IFC5 alpha output shape against the current IFC5 development schema/import conventions. The older ifcx_validate_viewer_compatibility name is kept as an alias for existing clients, but the buildingSMART viewer is not treated as the target spec.

Previewing

"Show me a preview of the model"

Returns a viewer-shaped tree and scene summary. You can also export:

• glTF — scene.gltf + scene.bin for any 3D viewer.

• Three.js — self-contained index.html you can open in a browser.

Exporting

"Write the model in tiered format to ./output/"

Three output formats are available: alpha JSON (single .ifcx), tiered (index.ifcx + NDJSON tables), and zipped post-alpha (.ifcx ZIP package).

Planning

"Plan a model for a hospital wing with mechanical systems"

The planner analyzes your intent and returns a step-by-step authoring plan with IDs, layers, types, geometry tiers, and an ordered tool-call recipe — without modifying any draft.

Typical Conversation

You: Create an IFCX model for a small school campus

You: Add a site, one building with 2 storeys (ground at 0m, first at 4m)

You: Create a concrete wall type, then place exterior walls
     around a 20x12m rectangle on the ground floor

You: Add 4 windows evenly spaced on the south wall

You: Add a DHW pipe network running east-west at ceiling level

You: Classify all walls as Uniclass Ss_25_10_30 and resolve via bSDD

You: Add georeferencing for Zurich (EPSG:2056)

You: Validate the model and show me any issues

You: Export a Three.js preview so I can check it in the browser

You: Write the final model in tiered format to ./output/

Things to Know

• Everything is in-memory. Export your model before stopping the server.

• Session IDs identify drafts. You can have multiple models open at once.

• bSDD lookups are cached locally in .ifcx-mcp-cache/bsdd/.

• Publishing is safe by default — dry-run mode unless you explicitly pass dryRun: false.

• Ask to "list my drafts" or "show the model tree" at any time to see current state.

Tools

Drafts

• ifcx_capabilities Report the available IFCX and IFClite adapter capabilities.

• ifcx_plan_model Plan an authoring run from natural-language or structured intent. It returns IDs, layers, imports, types, elements, geometry tiers, schemas, write targets, and an ordered tool-call recipe. It does not mutate a draft.

• ifcx_create_model Create an empty IFCX alpha draft with standard IFCX imports and provenance.

• ifcx_list_drafts List drafts currently held by the running server process.

IFC Structure

• ifcx_create_spatial_structure Create a project/site/building/storey tree, optionally with a space.

• ifcx_create_type Create a reusable type node, for example IfcWallType, IfcWindowType, or IfcPipeSegmentType.

• ifcx_create_element Create an element occurrence with class, name, recognized IFC5 properties, material, placement, and an optional parent attachment. Legacy properties and quantity inputs are normalized into direct bsi::ifc::prop::* attributes when the current schema supports them.

• ifcx_instantiate_type Create an occurrence that inherits from an existing type node.

Geometry

• ifcx_create_geometry_mesh Create a body node from points and faceVertexIndices, then attach it to an owner element.

• ifcx_create_geometry_proc Create a procedural geometry hint, such as extrude, sweep, revolve, or boolean.

• ifcx_create_geometry_brep Attach an OCCT BREP or STEP AP242 BRep payload to a node.

• ifcx_create_geometry_curve Attach a polyline, arc, circle, B-spline, or composite curve payload to a node.

Rich Factories

• ifcx_create_wall_from_axis Create a wall occurrence from a start/end axis, including direct IFC5 length/height properties, mesh body, material, and optional type inheritance.

• ifcx_create_window_with_void Create a window occurrence and a procedural void hint tied to its host wall.

• ifcx_create_pipe_network_with_ports Create a pipe sweep with start/end IfcDistributionPort nodes.

• ifcx_create_storey_grid Create an IfcGrid with X/Y curve axes attached to a storey.

Metadata Layers

• ifcx_create_material Add material and optional PBR material data to a node.

• ifcx_create_classification_layer Attach CCI, NL-SfB, bSDD, or other classification references.

• ifcx_resolve_bsdd_classification Resolve IFC/bSDD classification data from cache, from live bSDD when allowLive: true, or as a deterministic offline URI.

• ifcx_create_georeference_layer Add EPSG coordinate attributes and optional WKT CRS text.

• ifcx_create_patch_layer Create a delta layer over an existing draft. The patch imports the base draft ID and contains only the requested changes.

Validation And Preview

• ifcx_validate_created_model Check missing references, repeated path opinions, cycles, missing local schemas, and mesh index sanity. Pass engine: "ifcx-core" or engine: "ifc-lite" to also run the IFClite IFCX parser/adapter.

• ifcx_validate_ifc5_compliance Check the sanitized alpha export against the current IFC5 development imports and attribute shapes. Standard imported schemas stay imported; local schemas are only required for non-standard extension attributes.

• ifcx_validate_ids Validate a draft against IDS XML using @ifc-lite/ids. The server builds an IFCX-backed accessor for entity type, properties, classifications, materials, and parents.

• ifcx_create_bcf_from_validation Convert an IDS validation report into a serializable BCF topic summary using @ifc-lite/bcf.

• ifcx_preview_created_model Return a composed, viewer-shaped tree plus summary counts and geometry bounds.

Write And Publish

• ifcx_write_alpha Write a single alpha JSON .ifcx.

• ifcx_write_tiered Write index.ifcx plus NDJSON attribute tables.

• ifcx_write_zipped Write a zipped post-alpha .ifcx package containing index.json and NDJSON tables.

• ifcx_write_bcf_from_ids Validate a draft against IDS XML and write a .bcfzip issue package.

• ifcx_write_bcf_from_validation Write a .bcfzip issue package from an existing IDS validation report.

• ifcx_export_preview_gltf Export a simple glTF preview folder with scene.gltf, scene.bin, and preview-manifest.json.

• ifcx_export_preview_threejs Export a Three.js preview folder with index.html and the glTF scene.

• ifcx_publish_layer_version Publish a zipped draft to an IFCX layer API. This defaults to dry-run unless dryRun: false is passed.

Layer History

• ifcx_explain_layer_history Explain which node opinions introduced or overrode children, inherits, and attributes.

• ifcx_explain_patch_effect Compare a base draft and patch draft, then report added, removed, and changed nodes/attributes.

Some older tool names are kept as aliases while the interface settles, such as ifcx_export_alpha, ifcx_export_tiered, ifcx_add_mesh_geometry, and ifcx_validate_draft.

Resources

The server also exposes MCP resources:

• ifcx://drafts Current in-memory draft summaries.

• ifcx://draft/{sessionId}/tree Viewer-shaped composed tree for one draft.

• ifcx://draft/{sessionId}/scene Scene summary with tree, mesh/procedural counts, and bounds.

Integration Test

The integration test test/mcp-elaborate.test.ts drives the complete authoring workflow through MCP calls. It creates a two-storey model with walls, windows, domestic hot water pipes, ports, mesh geometry, procedural geometry, BRep and curve payloads, a storey grid, material/PBR data, classifications, bSDD resolution, georeferencing, a patch layer, preview resources, glTF/Three.js preview artifacts, and all three IFCX write formats.

npm run test:mcp

Output Formats

Alpha JSON:

model.ifcx

Tiered:

index.ifcx
ifcx.geom.mesh.ndjson
ifcx.geom.brep.ndjson
ifcx.geom.curve.ndjson
ifcx.geom.proc.ndjson
ifcx.semantics.ndjson

Zipped post-alpha:

model-post-alpha.ifcx

Preview:

scene.gltf
scene.bin
preview-manifest.json
index.html

The zipped package contains:

index.json
ifcx.geom.mesh.ndjson
ifcx.geom.brep.ndjson
ifcx.geom.curve.ndjson
ifcx.geom.proc.ndjson
ifcx.semantics.ndjson

BCF:

ids-validation.bcfzip

Publishing

ifcx_publish_layer_version is intentionally conservative.

By default:

{ "dryRun": true }

In dry-run mode it validates the draft and returns the target URL, layer ID, generated version ID, and blob ID, but does not upload.

With dryRun: false, it calls:

PUT  {baseUrl}/ifcx-api/upload/{blobId}
POST {baseUrl}/ifcx-api/layers/{layerId}/versions

Only use live publishing against an API endpoint you control.

Development

npm run check
npm run test
npm run test:mcp
npm run build

npm run test tests the authoring kernel directly.

npm run test:mcp builds the project, starts the MCP server over stdio with the SDK client transport, and drives the complete authoring workflow through MCP calls.

Project Layout

src/server.ts                         MCP server and tool/resource registration
src/ifcx-authoring/authoring-session.ts
src/ifcx-authoring/alpha-builder.ts
src/ifcx-authoring/tiered-builder.ts
src/ifcx-authoring/element-factories.ts
src/ifcx-authoring/geometry-factories.ts
src/ifcx-authoring/advanced-geometry.ts
src/ifcx-authoring/rich-factories.ts
src/ifcx-authoring/planner.ts
src/ifcx-authoring/preview-exporter.ts
src/ifcx-authoring/layer-history.ts
src/ifcx-authoring/validation-pipeline.ts
src/ifcx-authoring/patch-builder.ts
src/ifcx-authoring/writers.ts
src/adapters/bsdd-adapter.ts
src/adapters/ifc-lite-adapter.ts
src/adapters/ifcx-core-adapter.ts
test/authoring.test.ts
test/mcp-elaborate.test.ts

The src/ifcx/* files are compatibility re-exports for early imports. New code should import from src/ifcx-authoring.

Status

This is early implementation work. It already creates valid draft structures and writes the current target formats, but the authoring vocabulary will keep expanding as the IFCX examples and layer API mature.