From 607acd3c978fb0533818636fd8c1228105c16bf6 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:57:51 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20add=20HR-specific=20content=20and=20auth=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 10 ++++-- README.md | 86 +++++++++++++++++++++++++++++++++++----------------- package.json | 2 +- 3 files changed, 68 insertions(+), 30 deletions(-) diff --git a/.env.example b/.env.example index 4a63def..b33f832 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,8 @@ -# BambooHR API Credentials -BAMBOOHR_API_KEY=your-api-key-here +# BambooHR API Configuration +# Get your API key from: https://yourcompany.bamboohr.com/home/settings/api.php + +# Your BambooHR API key +BAMBOOHR_API_KEY=your_api_key_here + +# Your BambooHR company subdomain (e.g., "yourcompany" from yourcompany.bamboohr.com) +BAMBOOHR_COMPANY_DOMAIN=yourcompany diff --git a/README.md b/README.md index 96d32e4..62cba69 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,39 @@ **This MCP server gives AI direct access to your entire BambooHR workspace.** Instead of clicking through interfaces, you just *tell* it what you need. -### 🎯 BambooHR-Native Power Moves +### 🎯 HR Power Moves with BambooHR The AI can directly control your BambooHR account with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your BambooHR data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine BambooHR with other tools seamlessly +1. **Onboarding Automation** — "Pull all new hires from last month and generate personalized welcome emails with their start date, department, and manager info" + +2. **Time-Off Intelligence** — "Show me all pending PTO requests for the engineering team this quarter, flag conflicts, and suggest optimal approval schedules" + +3. **Performance Review Prep** — "For employee #4523, get their goals, recent performance notes, and time-off history — create a comprehensive review brief" + +4. **Directory Lookups** — "Find all employees in the Seattle office hired in the last 6 months with 'engineer' in their title" + +5. **Compliance Reporting** — "Export complete employee records for everyone in California with I-9 documents, filter by hire date, and format for audit" ### 🔗 The Real Power: Combining Tools AI can chain multiple BambooHR operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query employee directory → Filter by department → Generate org charts +- Check time-off balances → Identify burnout risk → Schedule 1-on-1s +- Pull goals data → Match with performance notes → Create review summaries ## 📦 What's Inside -**78 API tools** covering the entire BambooHR platform (HR & Payroll). +**7 API tools** covering core BambooHR HR operations: + +- `list_employees` — Get all employees with directory info +- `get_employee` — Detailed employee record with custom fields +- `list_time_off_requests` — PTO/leave requests with status filtering +- `request_time_off` — Submit time-off requests +- `list_goals` — Employee goals and performance tracking +- `get_directory` — Full company directory with contact info +- `list_files` — Employee documents and attachments All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +58,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your BambooHR API credentials** (see Authentication section below) +2. **Get your BambooHR API credentials:** + - Log into your BambooHR account + - Go to Account > API Keys + - Generate a new API key + - Note your company subdomain (e.g., `yourcompany` from `yourcompany.bamboohr.com`) 3. **Configure Claude Desktop:** @@ -58,9 +75,10 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "bamboohr": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/bamboohr-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/bamboohr-mcp-2026-complete/dist/index.js"], "env": { - "BAMBOOHR_API_KEY": "your-api-key-here" + "BAMBOOHR_API_KEY": "your-api-key-here", + "BAMBOOHR_COMPANY_DOMAIN": "yourcompany" } } } @@ -74,7 +92,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/bamboohr-mcp) 1. Click the button above -2. Set your BambooHR API credentials in Railway dashboard +2. Set `BAMBOOHR_API_KEY` and `BAMBOOHR_COMPANY_DOMAIN` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -83,24 +101,34 @@ All with proper error handling, automatic authentication, and TypeScript types. docker build -t bamboohr-mcp . docker run -p 3000:3000 \ -e BAMBOOHR_API_KEY=your-key \ + -e BAMBOOHR_COMPANY_DOMAIN=yourcompany \ bamboohr-mcp ``` ## 🔐 Authentication -See the official [BambooHR API documentation](https://docs.bamboohr.com) for authentication details. +BambooHR uses **API Key authentication** (Basic Auth with API key as username). -The MCP server handles token refresh automatically. +**Get your API credentials:** +1. BambooHR account → Account → API Keys +2. Generate new API key +3. Copy your company subdomain (from `yourcompany.bamboohr.com`) + +**API Documentation:** https://documentation.bamboohr.com/reference + +The MCP server handles authentication automatically via Basic Auth headers. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, you can use natural language. HR-specific examples: -- *"Show me recent activity in BambooHR"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +- *"Show me all employees in the engineering department hired in 2025"* +- *"Get pending time-off requests for next month"* +- *"Pull employee #1234's contact info, job title, and manager"* +- *"List all employees with 'Director' in their title"* +- *"Check time-off balances for the marketing team"* +- *"Show me Sarah Chen's performance goals and recent documents"* +- *"Generate a directory report of the SF office sorted by hire date"* ## 🛠️ Development @@ -132,18 +160,22 @@ npm run test:coverage # Coverage report ## 🐛 Troubleshooting ### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +- Verify your API key is correct (regenerate if needed) +- Check that your company domain is just the subdomain (not the full URL) +- Ensure your API key has the necessary permissions ### "Tools not appearing in Claude" - Restart Claude Desktop after updating config - Check that the path in `claude_desktop_config.json` is absolute - Verify the build completed successfully (`dist/index.js` exists) +### "Company domain error" +- Use only the subdomain: `yourcompany` NOT `yourcompany.bamboohr.com` +- Check for typos in your company domain + ## 📖 Resources -- [BambooHR API Documentation](https://docs.bamboohr.com) +- [BambooHR API Documentation](https://documentation.bamboohr.com/reference) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +195,10 @@ MIT License - see [LICENSE](LICENSE) for details ## 🙏 Credits -Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software. Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage). diff --git a/package.json b/package.json index 705329e..5dda65a 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for BambooHR API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",