BambooHR MCP Server

A complete Model Context Protocol (MCP) server for BambooHR with 47 tools and 18 React-based UI apps.

Features

🔧 47 MCP Tools

Employee Management (9 tools)

• list_employees - List all employees with filtering

• get_employee - Get detailed employee information

• create_employee - Create new employee records

• update_employee - Update employee information

• get_employee_directory - Get full employee directory

• get_custom_fields - List all custom fields

• get_employee_field_values - Get specific field values

• get_employee_photo - Download employee photos

• upload_employee_photo - Upload employee photos

Time Off (8 tools)

• list_time_off_requests - List time off requests with filtering

• get_time_off_request - Get specific request details

• create_time_off_request - Create new time off requests

• update_time_off_request_status - Approve/deny requests

• list_time_off_policies - List all policies

• get_time_off_balances - Get employee balances

• list_time_off_types - List all time off types

• estimate_future_balance - Estimate future balances

Reports (3 tools)

• run_custom_report - Run custom reports with filters

• list_reports - List all available reports

• get_company_report - Get standard company reports

Tables (4 tools)

• list_tables - List all custom tables

• get_table_rows - Get table data

• add_table_row - Add new table rows

• update_table_row - Update table rows

Benefits (4 tools)

• list_benefit_plans - List all benefit plans

• get_benefit_plan - Get plan details

• list_benefit_enrollments - List employee enrollments

• list_benefit_dependents - List dependents

Payroll (3 tools)

• list_pay_stubs - List employee pay stubs

• get_payroll_data - Get payroll information

• list_payroll_deductions - List deductions

Goals (6 tools)

• list_goals - List employee goals

• get_goal - Get goal details

• create_goal - Create new goals

• update_goal - Update goals

• close_goal - Close/complete goals

• list_goal_comments - List goal comments

Training (6 tools)

• list_training_courses - List courses

• get_training_course - Get course details

• create_training_course - Assign courses

• update_training_course - Update assignments

• list_training_categories - List categories

• list_training_types - List training types

Files (4 tools)

• list_employee_files - List employee files

• get_employee_file - Download files

• upload_employee_file - Upload files

• list_file_categories - List file categories

Webhooks (3 tools)

• list_webhooks - List all webhooks

• create_webhook - Create new webhooks

• delete_webhook - Delete webhooks

🎨 18 React UI Apps

1. employee-dashboard - Overview dashboard with key metrics

2. employee-directory - Searchable employee directory

3. employee-detail - Detailed employee profile view

4. time-off-calendar - Visual time off calendar

5. time-off-requests - Request management interface

6. time-off-balances - Balance tracking and accrual

7. benefits-overview - Benefits summary

8. benefits-enrollment - Step-by-step enrollment wizard

9. payroll-dashboard - Payroll overview and pay stubs

10. goal-tracker - Goal management and progress

11. training-catalog - Available courses catalog

12. training-progress - Course progress and certifications

13. file-manager - Document management

14. org-chart - Visual organization chart

15. headcount-analytics - Workforce analytics

16. turnover-report - Turnover tracking and analysis

17. new-hires - New hire tracking and onboarding

18. report-builder - Custom report builder

19. custom-report - Custom report viewer

Related MCP server: Greenhouse MCP

Installation

npm install

Configuration

Set the following environment variables:

export BAMBOOHR_COMPANY_DOMAIN="your-company"
export BAMBOOHR_API_KEY="your-api-key"

Usage

As MCP Server

npm run build
npm start

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bamboohr": {
      "command": "node",
      "args": ["/path/to/bamboohr/dist/main.js"],
      "env": {
        "BAMBOOHR_COMPANY_DOMAIN": "your-company",
        "BAMBOOHR_API_KEY": "your-api-key"
      }
    }
  }
}

API Reference

BambooHR API v1

Base URL: https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/

Authentication: Basic Auth with API key as username, "x" as password

Architecture

src/
├── clients/
│   └── bamboohr.ts          # API client with error handling
├── tools/
│   ├── employees-tools.ts   # Employee management tools
│   ├── time-off-tools.ts    # Time off tools
│   ├── reports-tools.ts     # Reporting tools
│   ├── tables-tools.ts      # Custom tables tools
│   ├── benefits-tools.ts    # Benefits tools
│   ├── payroll-tools.ts     # Payroll tools
│   ├── goals-tools.ts       # Goals tools
│   ├── training-tools.ts    # Training tools
│   ├── files-tools.ts       # File management tools
│   └── webhooks-tools.ts    # Webhook tools
├── types/
│   └── index.ts             # TypeScript type definitions
├── ui/
│   └── react-app/           # 18+ React UI components
├── server.ts                # MCP server implementation
└── main.ts                  # Entry point

Development

# Watch mode
npm run dev

# Build
npm run build

# Start
npm start

Error Handling

The client includes comprehensive error handling for:

• 400 Bad Request

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 429 Rate Limit

• 500 Internal Server Error

• Network errors

All errors are returned in a consistent format:

{
  "success": false,
  "error": "Error message",
  "status": 400
}

Resources

The server exposes two MCP resources:

• bamboohr://employees - Employee directory

• bamboohr://time-off - Time off requests

License

MIT

Contributing

Contributions welcome! Please ensure all tools follow the established patterns and include proper error handling.

Support

For BambooHR API documentation, visit: https://documentation.bamboohr.com/docs