cl-bamboohr-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cl-bamboohr-mcp Who's out of office today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | Cleanest TypeScript, proven test patterns, singleton client, core read tools (employee, time-off, files, meta) | |
Write operations |
| |
Analytics & reports | Workforce analytics, custom reports, dataset discovery, |
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.
Related MCP server: BambooHR MCP Server
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 buildEnvironment Variables
Variable | Required | Default | Description |
| Yes | — | BambooHR API key |
| Yes | — | Company subdomain |
| No |
| Enable debug logging |
| No |
| Cache TTL in ms (5 min) |
| No |
| Max retry attempts |
| No |
| Request timeout in ms |
| 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 onlyLicense
MIT
Available Tools
23 toolscreate-time-off-requestC
Create a new time-off request for an employee
Inputs: end (required), start (required), amount (required), employeeId (required), +3 more.
discover-datasetsA
List all available BambooHR datasets for analytics queries
Inputs: no named parameters.
discover-fieldsA
List available fields for a specific BambooHR dataset
Inputs: datasetId (required).
estimate-time-off-balanceA
Estimate future time-off balance for an employee on a given date
Inputs: end (required), employeeId (required).
find-employeeA
Search the employee directory by name, email, department, or job title
Inputs: query (required).
get-company-fileA
Get metadata for a specific company file
Inputs: fileId (required).
get-departmentsA
Get all departments in the company
Inputs: no named parameters.
get-employeeB
Get detailed information about a specific employee by their ID
Inputs: employeeId (required), fields.
get-employee-directoryB
Get the full company employee directory
Inputs: no named parameters.
get-employee-filesB
List all files for a specific employee organized by category
Inputs: employeeId (required).
get-employee-goalsA
Get performance goals for a specific employee
Inputs: employeeId (required).
get-employee-photoB
Get the URL for an employee photo in a specific size
Inputs: employeeId (required), size.
get-meta-fieldsB
Get BambooHR field metadata. Optionally filter by type: list, time_off_type, time_off_policy
Inputs: type.
get-team-infoC
Get team members for a specific supervisor/manager from the employee directory
Inputs: department, supervisorId.
get-time-off-requestsA
Get time-off requests filtered by date range, employee, status, or action
Inputs: end (required), start (required), action, status, +1 more.
get-whos-outA
Get a list of employees who are currently out or will be out in a date range
Inputs: end, start.
list-company-filesA
List all company-level files organized by category
Inputs: no named parameters.
list-custom-reportsA
List all saved custom reports available in BambooHR
Inputs: no named parameters.
list-report-presetsA
List built-in field-set presets that run-adhoc-report can execute by name
Inputs: no named parameters.
run-adhoc-reportA
Run an ad-hoc custom report by posting a field list to BambooHR. Use either a saved preset (presetName) or pass an explicit fields array. Returns JSON unless format=CSV. Set onlyCurrent=false to include terminated employees.
Inputs: title, fields, format, presetName, +1 more.
run-custom-reportB
Execute a saved custom report and get results
Inputs: reportId (required), format.
update-employeeA
Update employee information. Fields may be restricted by BAMBOO_UPDATE_ALLOWED_FIELDS env var.
Inputs: employeeId (required), fieldsJson (required).
workforce-analyticsB
Run an analytics query against a BambooHR dataset with optional filters
Inputs: datasetId (required), fields, filtersJson.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools target distinct BambooHR resources/actions (employee, time off, files, reports), but there is some potential confusion among directory tools (get-employee-directory/find-employee/get-team-info) and metadata/reporting tools (discover-fields/get-meta-fields/list-report-presets). Descriptions are clear enough for an agent to pick correctly in most cases.
Tool names overwhelmingly follow a verb_noun hyphenated convention (get-employee, list-company-files, run-custom-report). Minor deviations like the noun-only 'workforce-analytics' and the synonym mix of list/get/find/discover keep it from being a perfect 5.
23 tools is on the heavier side, covering several BambooHR subdomains (directory, time off, files, reporting). The count is defensible for an HR suite, but it exceeds the range where each tool is immediately memorable and starts to feel like a large API surface.
The set covers employee lookup/update, time-off visibility/creation, file metadata, and reporting/analytics, so core workflows are present. Obvious gaps remain: no employee create/delete, no time-off cancel/approval, no file upload/download, and custom reports can be run but not created or modified.
Maintenance
Related MCP Connectors
MCP server for SmartHR — employees, departments, dependents and employee invitations.
isolved and ApplicantPro jobs, tenant discovery, and change detection as an MCP server.
MCP server for Talenta — read employee, attendance, leave, payroll and recruitment data.
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that provides access to Personio's HR and personnel data through the Personnel API, allowing interaction with employee records, HR systems, and personnel management functions.-
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for BambooHR with 47 tools covering employee management, time off, reports, benefits, payroll, goals, training, files, and webhooks, plus 18 React-based UI apps.MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for BambooHR that enables safe AI assistant access to employee records, time-off, files, and directories via natural language queries.10MIT
- AlicenseAqualityCmaintenanceMCP server for the Personio HR API with employee and HR profiles, enabling self-service and HR operations like managing absences, attendances, documents, and organizational data.10Apache 2.0