MCP server package

Reference for the Tacit MCP server: tools, parameters, and configuration.

Overview

The Tacit MCP server exposes Tacit building data as tools for AI assistants. It connects to your Tacit account via API key and provides read-only access to buildings, equipment, points, zones, and systems.

Compatible with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

For setup instructions, see Connect AI to your building.

Installation

Clone the MCP server from GitHub and install dependencies:

git clone https://github.com/ucl-sbde/tacit-mcp.git
cd tacit-mcp
npm install
npm run build

Then configure your AI client to use the local server (see setup guide).

Environment variables

Variable	Required	Default	Description
TACIT_API_KEY	Yes	-	Your Tacit API key (Bearer token)
TACIT_API_URL	No	https://app.betacit.com	API base URL

Tool reference

The MCP server exposes four tools:

tacit_list_sites

List all building sites the API key has access to. Call this first to discover available site IDs.

Parameters: None

Returns: Site name, ID, address, city, country, timezone.

---

tacit_graphql

Execute a GraphQL query against the Tacit building digital twin API. Compose any query using the Brick-compliant schema. Supports nested fields, filtering by Brick class, supply chain traversal (upstream/downstream), and recursive location hierarchy.

Use tacit_list_sites first to get a valid site ID, then construct queries freely.

Parameter	Type	Required	Description
site_id	string	Yes	Site ID from tacit_list_sites
query	string	Yes	GraphQL query string
variables	string	No	JSON-encoded variables object (siteId is auto-injected)

The tool automatically injects siteId into the query variables from the site_id parameter. The full GraphQL schema reference is embedded in the tool description so the AI model can compose queries without external documentation.

---

tacit_timeseries

Query historical or live sensor data for one or more points. Points are identified by their timeseriesId (UUID). Use tacit_graphql first to find points and their timeseriesId values.

Parameter	Type	Required	Description
site_id	string	Yes	Site ID
point_ids	string	Yes	Comma-separated timeseriesId UUIDs (max 200)
start	string	No	Start time: relative like "-1h", "-24h", "-7d" or ISO 8601. Default: "-1h"
end	string	No	End time: "now()" or ISO 8601. Default: "now()"
window	string	No	Aggregation window like "5m", "1h", "1d". Only with aggregate.
aggregate	string	No	Aggregation function: mean, min, max, sum, count, first, last. Default: "mean"
limit	number	No	Max records per point (1-10000). Default: 1000

Response includes: query.timezone declares the site’s IANA timezone (e.g., Europe/London). All timestamps in the response are in this timezone with the UTC offset embedded (e.g., +00:00 for GMT, +01:00 for BST). When a window is specified, timestamps are snapped to the window boundary.

Common patterns:

• Last hour raw data: start="-1h" (default)
• Daily averages for a week: start="-7d", window="1d", aggregate="mean"
• Last 24h at 15-minute intervals: start="-24h", window="15m"

For current/live values, use tacit_graphql with the currentValue { value timestamp quality } field on Point instead of this tool.

---

tacit_list_files

List documents and files associated with a site. Returns metadata for spec sheets, maintenance documents, BIM source files, 3D models, and knowledge graph data.

Parameter	Type	Required	Description
site_id	string	Yes	Site ID from tacit_list_sites
category	string	No	Filter by file type: kg-csv, model-3d, bim-source, spec-sheet, maintenance, other
entity_uri	string	No	Filter by associated entity URI (from GraphQL entity.uri field)

Returns: Files grouped by category with name, size, and upload date.