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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.butlr.io/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.