Skip to main content
Glama
cl-bamboohr-mcp
by iseletsk

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.

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 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

Available Tools

23 tools
create-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

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for BambooHR that enables safe AI assistant access to employee records, time-off, files, and directories via natural language queries.
      10
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      10
      Apache 2.0