bsdd-mcp

An MCP server that gives an AI assistant read-only access to the buildingSMART Data Dictionary (bSDD) — the shared library of construction classifications (IFC, ETIM, Uniclass, national dictionaries, …), their classes, properties, units and relations.

It talks to the public bSDD API at https://api.bsdd.buildingsmart.org. No account, API key or login is needed: every endpoint used here is part of the unsecured, public API.

Install

git clone <this repo>
cd bsdd-mcp
npm install       # builds automatically via the prepare script

Use it with Claude Code

claude mcp add bsdd -- node /absolute/path/to/bsdd-mcp/dist/index.js

Use it with Claude Cowork / Claude Desktop

Cowork installs local MCP servers as .mcpb bundles. Build one:

npm run bundle     # -> build/bsdd-mcp-<version>.mcpb

The bundle is self-contained (compiled server + production dependencies), so it does not depend on this checkout after installation. Install it from Settings → Connectors → Install extension… and pick the .mcpb file. Local MCP servers run natively on your machine, not inside the Cowork sandbox, so the server reaches the bSDD API over your normal network connection.

If your workplace disables desktop extensions, add the server by hand instead under Settings → Developer → Local MCP servers:

{
  "mcpServers": {
    "bsdd": {
      "command": "node",
      "args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
    }
  }
}

Use it with any other MCP client

Add this to the client's MCP configuration (claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "bsdd": {
      "command": "node",
      "args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
    }
  }
}

Tools

Tool	What it does	bSDD endpoint
bsdd_list_dictionaries	List/filter the published dictionaries	GET /api/Dictionary/v1
bsdd_list_dictionary_classes	Browse the classes of one dictionary (flat or nested)	GET /api/Dictionary/v1/Classes
bsdd_list_dictionary_properties	Browse the properties of one dictionary	GET /api/Dictionary/v1/Properties
bsdd_search_classes	Free-text class search across dictionaries	GET /api/Class/Search/v1
bsdd_search_text	Free-text search returning classes and properties	GET /api/TextSearch/v2
bsdd_get_class	Class details, optionally with child classes and relations	GET /api/Class/v1
bsdd_get_class_properties	The properties of a class, with data types and units	GET /api/Class/Properties/v1
bsdd_get_class_relations	Forward or reverse relations of a class	GET /api/Class/Relations/v1
bsdd_get_property	Property details	GET /api/Property/v5
bsdd_get_property_classes	Which classes use a property	GET /api/Property/Classes/v1
bsdd_get_property_value	Details of one value of an enumeration	GET /api/PropertyValue/v2
bsdd_list_reference_data	Countries, languages, units or reference documents	GET /api/Country|Language|Unit|ReferenceDocument/v1

All tools are read-only and annotated as such.

Typical flow

1. bsdd_list_dictionaries — find the dictionary URI you need. URIs always contain a version, e.g. https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3; the version can be replaced by latest.
2. bsdd_search_classes — find a class by name, e.g. "which class describes a wall?".
3. bsdd_get_class for the definition, bsdd_get_class_properties for its properties, bsdd_get_class_relations to map it onto classes in other dictionaries.

Configuration

All optional, read from the environment:

Variable	Default	Purpose
BSDD_API_BASE_URL	https://api.bsdd.buildingsmart.org	Point at another bSDD instance
BSDD_TIMEOUT_MS	30000	Per-request timeout
BSDD_MAX_RETRIES	3	Retries on HTTP 429 / 5xx
BSDD_USER_AGENT	bsdd-mcp/<version>	User-Agent sent to bSDD

Notes on the bSDD API

These are behaviours of the upstream API that the server works around, and that are worth knowing when reading the results:

• Rate limiting. bSDD answers with HTTP 429 and a message like "Try again in 4 seconds". The client honours Retry-After (and that message) and retries with exponential backoff.
• IFC and text search. /api/TextSearch/v2 treats the IFC dictionary as a preview dictionary and leaves it out unless IncludePreview is set, so bsdd_search_text sets it by default. bsdd_search_classes (/api/Class/Search/v1) always covers IFC.
• Class properties. The IncludeClassProperties option of /api/Class/v1 is deprecated and heavily rate limited; bsdd_get_class_properties uses the dedicated paginated endpoint instead.
• Page size. The API returns up to 1000 items per call. These tools default to 50 to keep responses reasonable for a model context; pass limit explicitly when you need more.

Development

npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check only
npm test           # build + unit tests (no network; fetch is stubbed)
npm run test:live  # calls every tool against the real bSDD API

License

MIT — see LICENSE. bSDD content itself is published by buildingSMART International and its dictionary owners under their own licenses (each dictionary reports its license field).