cl-bamboohr-mcp

cl-bamboohr-mcp

A comprehensive BambooHR MCP (Model Context Protocol) server providing read/write access to employee data, time-off, files, analytics, and reports.

Background

This project was built by evaluating three existing open-source BambooHR MCP servers, then combining the best architecture, features, and API coverage from all three into a single, secure, well-tested server:

| Source | Repo | What we took | |--------|------|-------------| | Architectural base | evrimalacan/mcp-bamboohr | Cleanest TypeScript, proven test patterns, singleton client, core read tools (employee, time-off, files, meta) | | Write operations | a-isakov/bamboohr-mcp | update-employee, create-time-off-request, employee files, departments | | Analytics & reports | zuharz/bamboo-mcp-unofficial | Workforce analytics, custom reports, dataset discovery, find-employee, get-team-info, caching/retry patterns |

All three source repos are MIT-licensed. None were production-quality individually (0-2 GitHub stars, security issues like API key leaks in logs, missing input validation). This project addresses those gaps with proper input validation, credential sanitization, field allowlists for write operations, and comprehensive test coverage.

The entire server — code, tests, and documentation — was generated by Claude (Opus 4.6) based on a detailed architecture plan derived from auditing the three source repos.

Features

• 21 tools covering the full BambooHR API surface
• Read and write operations (employee updates, time-off requests)
• Built-in caching, retry with exponential backoff, and error categorization
• Security hardening: input validation, credential sanitization, field allowlists
• TypeScript with 100+ tests

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bamboohr": {
      "command": "node",
      "args": ["/path/to/cl-bamboohr-mcp/dist/index.js"],
      "env": {
        "BAMBOO_API_TOKEN": "your-api-key",
        "BAMBOO_COMPANY_DOMAIN": "your-company"
      }
    }
  }
}

From Source

git clone https://github.com/iseletsk/cl-bamboohr-mcp.git
cd cl-bamboohr-mcp
npm install
npm run build

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BAMBOO_API_TOKEN | Yes | — | BambooHR API key | | BAMBOO_COMPANY_DOMAIN | Yes | — | Company subdomain | | DEBUG | No | false | Enable debug logging | | BAMBOO_CACHE_TTL_MS | No | 300000 | Cache TTL in ms (5 min) | | BAMBOO_MAX_RETRIES | No | 3 | Max retry attempts | | BAMBOO_REQUEST_TIMEOUT_MS | No | 30000 | Request timeout in ms | | BAMBOO_UPDATE_ALLOWED_FIELDS | No | — | Comma-separated allowlist for update-employee |

Tools

Employee Management (6)

• get-employee — Get employee details by ID
• find-employee — Search directory by name/email/department
• update-employee — Update employee fields (WRITE)
• get-employee-directory — Full company directory
• get-employee-photo — Employee photo URL
• get-employee-goals — Performance goals

Time Off (4)

• get-whos-out — Who's currently out
• get-time-off-requests — Filter requests by date/status
• estimate-time-off-balance — Future balance estimate
• create-time-off-request — Create a request (WRITE)

Files (3)

• list-company-files — Company files by category
• get-company-file — File metadata
• get-employee-files — Employee files by category

Organization (3)

• get-meta-fields — Field metadata (filterable by type)
• get-departments — All departments
• get-team-info — Team members by supervisor/department

Analytics (3)

• discover-datasets — Available datasets
• discover-fields — Fields in a dataset
• workforce-analytics — Query datasets with filters

Reports (2)

• list-custom-reports — Saved reports
• run-custom-report — Execute a report

Security

• All IDs validated (numeric regex for employee/file/report IDs)
• Subdomain validated at startup
• No credential logging — auth stripped from error objects
• Optional field allowlist for write operations
• Dates and enums validated via Zod schemas

Development

npm test              # Run tests
npm run test:coverage # Run with coverage
npm run build         # TypeScript compilation
npm run lint          # Type check only

License

MIT