MCP Server
The Butlr MCP Server connects AI assistants to Butlr's occupancy sensing platform through the Model Context Protocol. 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.
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.
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
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.
Installation
The server is distributed on npm as @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:
Authentication
The MCP Server authenticates using the same client credentials 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 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 in the repo.
Links
Last updated