BambooHR MCP Server for Node.js & TypeScript

Overview

BambooHR MCP Server for Node.js & TypeScript is a lightweight Model Context Protocol (MCP) integration that wraps the BambooHR REST API with a type-safe, promise-based interface. Built with TypeScript, it exposes typed models and helper functions to make common BambooHR operations (employee directory, time entries, time off, and project/time submissions) straightforward from Node.js applications or serverless functions.

This library is useful when you want predictable TypeScript types for BambooHR responses, a small surface area to call the API, and a simple pattern to extend with additional endpoints. It’s designed to be easy to install, easy to call from server-side code, and easy to expand with new API helpers.

Features

• Complete TypeScript types for models and API responses
• Promise-based API methods suitable for async/await
• High-level helper functions for common BambooHR workflows
• Minimal dependencies and a small code surface for easy extension
• Ready to use in Node.js, TypeScript projects, and serverless environments

Installation / Configuration

Clone the repository and install dependencies:

# Clone the repo
git clone https://github.com/encoreshao/bamboohr-mcp.git
cd bamboohr-mcp

# Install
npm install

Build (if using TypeScript locally) and run tests (if provided):

npm run build
npm test

Environment variables

You can pass credentials directly to API calls, but environment variables make local development and CI simpler. Create a .env file or set these in your environment:

BAMBOOHR_TOKEN=your_api_token_here
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_EMPLOYEE_ID=123

Table: required environment variables

Tip: The API token is shown only once when created — store it securely (e.g., secrets manager).

Available Resources

The library exposes:

• BambooHRApi class — a low-level API wrapper that encapsulates authentication and HTTP calls.
• Helper functions — convenience wrappers for common tasks:
  • fetchEmployeeDirectory
  • fetchWhosOut
  • fetchProjects
  • fetchTimeEntries
  • submitWorkHours
  • getMe

All functions return Promises and use types defined in the project’s type definitions (e.g., src/utils/models.d.ts).

Example exports (simplified):

import {
  BambooHRApi,
  fetchEmployeeDirectory,
  fetchWhosOut,
  fetchProjects,
  submitWorkHours,
  getMe,
  fetchTimeEntries,
} from "bamboohr-mcp";

Use Cases

1. List employee directory (name, email, job title)

import { fetchEmployeeDirectory } from "bamboohr-mcp";

const token = process.env.BAMBOOHR_TOKEN!;
const domain = process.env.BAMBOOHR_COMPANY_DOMAIN!;

async function printDirectory() {
  const directory = await fetchEmployeeDirectory(token, domain);
  directory.employees.forEach(emp =>
    console.log(`${emp.displayName} — ${emp.workEmail} — ${emp.jobTitle}`)
  );
}

2. Check who is out today

import { fetchWhosOut } from "bamboohr-mcp";

async function printWhosOut() {
  const whosOut = await fetchWhosOut(process.env.BAMBOOHR_TOKEN!, process.env.BAMBOOHR_COMPANY_DOMAIN!);
  whosOut.forEach(o => console.log(`${o.employeeName}: ${o.startDate} → ${o.endDate}`));
}

3. Submit work hours to a project/task

import { fetchProjects, submitWorkHours } from "bamboohr-mcp";

const token = process.env.BAMBOOHR_TOKEN!;
const domain = process.env.BAMBOOHR_COMPANY_DOMAIN!;
const employeeID = process.env.BAMBOOHR_EMPLOYEE_ID!;

async function submitExample() {
  const projects = await fetchProjects(token, domain, employeeID);
  const project = projects.find(p => p.name.includes("Website"));
  const task = project?.tasks.find(t => t.name.includes("Development"));
  if (project && task) {
    await submitWorkHours(
      token, domain, employeeID,
      project.id, task.id,
      "2024-06-01", 4, "Development time"
    );
  }
}

Extending the Library

• Add new endpoints in src/apis/bamboohr.ts using the BambooHRApi class to keep authentication and request patterns consistent.
• Export new helpers from src/index.ts so consumers can import them directly.
• Use the provided TypeScript model definitions (src/utils/models.d.ts) when adding or returning new types.

Directory hints:

• src/apis — API call implementations
• src/utils — model/type definitions and helpers
• src/index.ts — public exports

Notes, Contributing & License

• All methods are asynchronous and return Promises; use try/catch or .catch for error handling.
• Contributions are welcome — open an issue or a pull request on the repository.
• This project uses the MIT License. See the LICENSE file in the repo for details.

Repository: https://github.com/encoreshao/bamboohr-mcp