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