@Shuji Bonji/Ifc Core

npm version CI License: MIT Built with Claude Cowork

日本語版 README はこちら

MCP server for IFC4.3 specification reference — search and retrieve IFC entity definitions, attributes, inheritance hierarchies, and PropertySets.

Unlike existing IFC-related MCP servers that operate on IFC model files (parse, extract, modify), this server provides access to the IFC specification itself as a structured reference. It enables AI to look up the correct definitions of entities, attributes, types, and constraints defined in the IFC4.3 standard (ISO 16739-1:2024).

Key Features

• Entity Search — find IFC entities by name or description keyword
• Entity Definition — retrieve complete definitions with attributes, inheritance, WHERE rules, and documentation
• Inheritance Tree — visualize ancestor chains and descendant hierarchies
• PropertySet Lookup — get or search PropertySet definitions with full documentation
• Dual Output — every tool supports both Markdown (human-readable) and JSON (structured) formats
• Pagination — configurable limit/offset for large result sets

Available Tools

Tool	Description
ifc_search_entity	Search entities by name or description keyword
ifc_get_entity	Get complete entity definition (attributes, inheritance, WHERE rules, docs)
ifc_get_inheritance	Show inheritance hierarchy (ancestors, descendants, or both)
ifc_get_propertyset	Get or search PropertySet definitions

Scope

What this MCP provides

• IFC4.3 specification reference: entity definitions, attributes, inheritance, WHERE rules, PropertySet definitions
• Structured lookup of the IFC standard (ISO 16739-1:2024) — a vocabulary/dictionary for AI
• Dual output (Markdown / JSON) suitable for both human reading and programmatic consumption

What this MCP does NOT provide

• IFC file (.ifc) parsing or extraction — use IfcOpenShell (Python) or web-ifc (TypeScript/WebAssembly) instead
• Geometry rendering or 3D visualization
• Schema version migration (IFC2x3 / IFC4 → IFC4.3) — currently IFC4.3 only
• Quantity information (Qto_*) — planned for a future release

If you need to operate on actual .ifc files at runtime, combine this MCP (for specification lookup) with a file-operation library (for data extraction).

Installation

npm (global)

npm install -g @shuji-bonji/ifc-core-mcp

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "ifc-core": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/ifc-core-mcp"]
    }
  }
}

Claude Code

claude mcp add ifc-core -- npx -y @shuji-bonji/ifc-core-mcp

From source

git clone https://github.com/shuji-bonji/ifc-core-mcp.git
cd ifc-core-mcp
npm install
npm run build
node dist/index.js

Running manually (after global install)

After npm install -g @shuji-bonji/ifc-core-mcp, the server can be started with:

ifc-core-mcp

The process communicates over stdio (MCP standard transport) and is intended to be launched by an MCP client (Claude Desktop, Claude Code, etc.) rather than invoked directly for interactive use.

Example Usage

Once installed, you can ask an MCP-enabled LLM (e.g., Claude) questions such as:

• "What attributes does IfcSpace have in IFC4.3?"
• "Show me the inheritance hierarchy from IfcBuildingElement down to leaf subtypes."
• "Find all IFC entities related to HVAC."
• "What PropertySets apply to IfcWall, and what properties do they contain?"
• "What is the definition of IfcMapConversion, and which attributes store CRS information?"

The LLM will invoke the appropriate tool (ifc_search_entity, ifc_get_entity, ifc_get_inheritance, or ifc_get_propertyset) and return structured results.

Data Coverage

The server covers the complete IFC4.3 schema:

Category	Count
Entities	876
Type Declarations	132
Enumerations	243
Select Types	61
Functions	48
Global Rules	2

Entities are organized across 4 IFC layers:

Layer	Entities	Description
Resource	392	Geometry, units, materials
Core	145	Kernel, product extensions
Shared	111	Walls, columns, beams, MEP
Domain	228	Architecture, HVAC, rail, roads

Architecture

Build time (one-time, Python):
  IFC.exp (EXPRESS schema) → ifc4x3-schema.json
  IFC4.3.x-development Markdown → ifc4x3-descriptions-*.json

Runtime (TypeScript MCP server):
  Pre-built JSON files → Map-based indexes → MCP tools

The server loads three pre-built JSON data files at startup and builds in-memory indexes (Maps) for O(1) entity lookups by name. The EXPRESS schema provides structural data (types, attributes, inheritance, WHERE rules), while the Markdown documentation provides semantic data (definitions, usage, history).

Data Sources & Licenses

• EXPRESS schema (IFC.exp) — from buildingSMART/IFC4.3.x-output
• Markdown documentation — from buildingSMART/IFC4.3.x-development
• IFC specification content is licensed under CC BY-ND 4.0 by buildingSMART International

Development

Prerequisites

• Node.js >= 22
• Python 3 + IfcOpenShell (only for data regeneration)

Commands

npm run build          # Compile TypeScript
npm run dev            # Watch mode with tsx
npm test               # Run all tests (unit + e2e)
npm run test:unit      # Unit tests only
npm run test:e2e       # E2E integration tests
npm run lint           # ESLint check
npm run format         # Prettier formatting
npm run prepare-data   # Regenerate data from raw sources (requires Python)

Tech Stack

• Runtime: TypeScript (strict), Node.js
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• Testing: Vitest (unit + e2e with actual MCP client)
• Linting: ESLint + Prettier
• CI/CD: GitHub Actions (lint → test → build → publish)

Roadmap

This server focuses on the IFC4.3 schema itself. Potential future directions under consideration:

• QuantitySet (Qto_*) support — add quantity definitions alongside PropertySets
• ifcJSON schema — complement the current EXPRESS-derived data
• Cross-version lookup — map IFC2x3 / IFC4 → IFC4.3 entities
• Sister MCP for IFC file operations — a separate project (planned, not yet released) for parsing and querying actual .ifc files, designed to pair with this reference server

Feedback and use-case reports are welcome via GitHub Issues.

Related Projects

• w3c-mcp — MCP server for W3C/WHATWG/IETF web specifications
• rfcxml-mcp — MCP server for IETF RFC documents (XML-based)
• epsg-mcp — MCP server for EPSG coordinate reference systems (useful when combined with IfcMapConversion)

License

MIT