# 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](https://github.com/evrimalacan/mcp-bamboohr) | Cleanest TypeScript, proven test patterns, singleton client, core read tools (employee, time-off, files, meta) |
| **Write operations** | [a-isakov/bamboohr-mcp](https://github.com/a-isakov/bamboohr-mcp) | `update-employee`, `create-time-off-request`, employee files, departments |
| **Analytics & reports** | [zuharz/bamboo-mcp-unofficial](https://github.com/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`:

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

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

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

## License

MIT