bamboohr

This MCP server provides a TypeScript-based client library for interacting with the BambooHR API. It exposes a BambooHRApi class along with helper functions such as fetchWhosOut, fetchProjects, submitWorkHours, getMe, fetchEmployeeDirectory, and fetchTimeEntries. Use the API to query employee directories, retrieve who’s out today, list projects and tasks for assigning work hours, submit time entries, and fetch current user details. The library is designed with type safety in mind, offering TypeScript types for models and API responses to reduce runtime errors. To start using it, install the MCP package in your project and import the provided methods, supplying your BambooHR token, company domain, and your employee ID as needed. Environment variables can also be used to supply these values automatically at runtime.

Prerequisites:\n- Node.js (≥ 14) and npm/yarn installed.\n- Access to a BambooHR account and an API token.\n\nInstall steps:\n1) Clone the repository or add the MCP package to your project:\n npm install bamboohr-mcp\n or, if you’re using it via the MCP server, run the MCP server command provided in mcp_config.\n2) Create a .env file (optional) with your BambooHR credentials:\n BAMBOOHR_TOKEN=your_api_token\n BAMBOOHR_COMPANY_DOMAIN=yourcompany\n BAMBOOHR_EMPLOYEE_ID=your_id\n3) Import and initialize the API in your TypeScript/JavaScript project:\n import { BambooHRApi, fetchEmployeeDirectory } from "bamboohr-mcp";\n const token = process.env.BAMBOOHR_TOKEN;\n const domain = process.env.BAMBOOHR_COMPANY_DOMAIN;\n const api = new BambooHRApi(token!, domain!);\n4) Use the provided helpers:\n const directory = await fetchEmployeeDirectory(token!, domain!);

Notes and tips:\n- Ensure your BambooHR API token has the necessary permissions for the endpoints you plan to use.\n- Store tokens securely; prefer environment variables over hard-coding.\n- If you encounter CORS or network issues, verify that your BambooHR domain is correct (the subdomain before .bamboohr.com).\n- The library provides TypeScript types for models and responses; enable strict mode in tsconfig to maximize type safety.\n- When debugging, log the raw API responses to understand the shape of data returned by BambooHR.\n- If starting the MCP server via npx, ensure you have network access to fetch and install the package at runtime.