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

Related MCP server: IFCX MCP

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

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:

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).