> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/mcp-server.md).

# MCP Server

The [**Butlr MCP Server**](https://github.com/butlrtechnologies/butlr-mcp) connects AI assistants to Butlr's occupancy sensing platform through the [Model Context Protocol](https://modelcontextprotocol.io). It lets tools like Claude Desktop, Claude Code, Cursor, and VS Code Copilot answer natural-language questions about your real-time space utilization, portfolio, and sensor health — without writing any API code.

{% hint style="info" %}
The MCP Server is a thin, **read-only** wrapper around the same GraphQL and Reporting APIs documented elsewhere in this site. It cannot modify any data in your Butlr account.
{% endhint %}

## What you can ask

* **Find available spaces** — "Are there any free conference rooms right now with capacity for 8?"
* **Monitor live occupancy** — "How busy is the cafe? Should I head there now?"
* **Analyze trends** — "Show me occupancy patterns for Floor 3 over the past week."
* **Search your portfolio** — "Find all rooms named 'huddle' across Building 2."
* **Check sensor health** — "Which sensors are offline or need battery replacement?"
* **Track foot traffic** — "How many people entered the main lobby today?"

## Available tools

| Tool                             | Purpose                                                             |
| -------------------------------- | ------------------------------------------------------------------- |
| `butlr_search_assets`            | Fuzzy-search sites, buildings, floors, rooms, and sensors by name   |
| `butlr_get_asset_details`        | Comprehensive details for specific assets by ID, with batch support |
| `butlr_hardware_snapshot`        | Online/offline status and battery levels across your portfolio      |
| `butlr_available_rooms`          | Currently unoccupied rooms, filterable by capacity and tags         |
| `butlr_space_busyness`           | Current occupancy with qualitative labels and trend comparison      |
| `butlr_traffic_flow`             | Entry/exit counts with hourly breakdown for traffic-mode sensors    |
| `butlr_list_topology`            | Org hierarchy tree with flexible depth control                      |
| `butlr_fetch_entity_details`     | Retrieve specific fields for entities by ID (minimal token usage)   |
| `butlr_get_occupancy_timeseries` | Historical occupancy data with configurable time ranges             |
| `butlr_get_current_occupancy`    | Real-time occupancy snapshot (last 5 minute median)                 |

For the authoritative, up-to-date list — including parameter schemas and response shapes — see the [repository README](https://github.com/butlrtechnologies/butlr-mcp#available-tools).

## Installation

The server is distributed on npm as [`@butlr/butlr-mcp-server`](https://www.npmjs.com/package/@butlr/butlr-mcp-server) and runs via `npx`, so no local install is required.

Copy-paste configuration for each supported client lives in the repo README:

* [Claude Desktop](https://github.com/butlrtechnologies/butlr-mcp#quick-start)
* [Claude Code](https://github.com/butlrtechnologies/butlr-mcp#quick-start)
* [VS Code (Copilot)](https://github.com/butlrtechnologies/butlr-mcp#quick-start)
* [Cursor](https://github.com/butlrtechnologies/butlr-mcp#quick-start)
* [Other MCP clients (stdio)](https://github.com/butlrtechnologies/butlr-mcp#quick-start)

## Authentication

The MCP Server authenticates using the same [client credentials](/getting-started/mint-client-credentials.md) used by the rest of the Butlr API. Set `BUTLR_CLIENT_ID` and `BUTLR_CLIENT_SECRET` in your MCP client's environment configuration — token refresh is handled automatically.

See the [Configuration table](https://github.com/butlrtechnologies/butlr-mcp#configuration) in the repo for all supported environment variables (base URL override, default timezone, cache TTL, debug logging).

## Security

* All tools enforce **read-only** API access — the server exposes no mutations.
* Credentials are read from environment variables only; never commit them to source control.
* Vulnerability disclosure: see [SECURITY.md](https://github.com/butlrtechnologies/butlr-mcp/blob/main/SECURITY.md) in the repo.

## Links

* [GitHub repository](https://github.com/butlrtechnologies/butlr-mcp)
* [npm package](https://www.npmjs.com/package/@butlr/butlr-mcp-server)
* [Model Context Protocol](https://modelcontextprotocol.io)