Butlr MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Butlr's occupancy sensing platform. Query real-time space utilization, search facility assets, and analyze occupancy patterns through natural language.

What you can do

• Find available spaces — "Are there any free conference rooms right now with capacity for 8?"
• Monitor 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?"

Prerequisites

• Node.js 18 or higher
• An MCP-compatible client (Claude Desktop, Claude Code, Codex CLI, VS Code, Cursor, etc.)
• Butlr API token — see Getting API Credentials

Quick Start

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "butlr": {
      "command": "npx",
      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
      "env": {
        "BUTLR_CLIENT_ID": "your_client_id",
        "BUTLR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

claude mcp add butlr \
  -e BUTLR_CLIENT_ID=your_client_id \
  -e BUTLR_CLIENT_SECRET=your_client_secret \
  -- npx -y @butlr/butlr-mcp-server@latest

Add with the codex mcp command:

codex mcp add butlr \
  --env BUTLR_CLIENT_ID=your_client_id \
  --env BUTLR_CLIENT_SECRET=your_client_secret \
  -- npx -y @butlr/butlr-mcp-server@latest

Or edit ~/.codex/config.toml directly:

[mcp_servers.butlr]
command = "npx"
args = ["-y", "@butlr/butlr-mcp-server@latest"]

[mcp_servers.butlr.env]
BUTLR_CLIENT_ID = "your_client_id"
BUTLR_CLIENT_SECRET = "your_client_secret"

Add to .vscode/mcp.json:

{
  "servers": {
    "butlr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
      "env": {
        "BUTLR_CLIENT_ID": "your_client_id",
        "BUTLR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "butlr": {
      "command": "npx",
      "args": ["-y", "@butlr/butlr-mcp-server@latest"],
      "env": {
        "BUTLR_CLIENT_ID": "your_client_id",
        "BUTLR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

For any MCP client that supports stdio transport, use this command:

npx -y @butlr/butlr-mcp-server@latest

Pass the required environment variables (BUTLR_CLIENT_ID, BUTLR_CLIENT_SECRET) through your client's configuration.

Available Tools

All tools are read-only — the server cannot modify any data in your Butlr account.

Configuration

Getting API Credentials

1. Log in to app.butlr.io
2. Click your username in the top-right corner, then Account Settings
3. Go to API Tokens and create a new token
4. Copy the Client ID and Client Secret

You need edit access to Butlr Studio to create API tokens. If you don't have edit permissions, ask someone in your organization who does, or contact your Butlr sales representative or submit a support ticket.

Troubleshooting

Authentication errors — Verify your BUTLR_CLIENT_ID and BUTLR_CLIENT_SECRET are correct. Tokens are refreshed automatically.

Rate limiting — The server handles rate limits automatically with retry logic. If you see persistent rate limit errors, reduce the frequency of requests.

No data returned — Ensure your organization has active sensors deployed. Use butlr_search_assets to verify your org has discoverable assets.

Debug logging — Set DEBUG=butlr-mcp in your environment to see detailed request/response logs on stderr.

Development

See CONTRIBUTING.md for full development workflow and standards.

npm install          # Install dependencies
npm run build        # Build TypeScript
npm test             # Run tests
npm run typecheck    # Type checking
npm run lint         # ESLint
npm run dev          # Dev with hot-reload
npm run dev:debug    # Dev with debug logging

Security

• All tools enforce read-only API access
• Never commit credentials to version control
• See SECURITY.md for vulnerability disclosure

License

MIT - see LICENSE