From 86734e67e55c3649136eea6676b4898a72dc2ef1 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:58:44 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20add=20HR/IT-specific=20content=20and=20OAuth=20details?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 14 ++++++-- README.md | 93 +++++++++++++++++++++++++++++++++++++--------------- package.json | 2 +- 3 files changed, 79 insertions(+), 30 deletions(-) diff --git a/.env.example b/.env.example index e19cba0..54d9753 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,12 @@ -# Rippling API Credentials -RIPPLING_API_KEY=your-api-key-here +# Rippling API Configuration +# Get your API credentials from: Rippling → Settings → Integrations → API + +# Your Rippling API key or OAuth token +# Supports OAuth 2.0 or API token authentication +RIPPLING_API_KEY=your_api_key_or_oauth_token_here + +# Required OAuth scopes (if using OAuth): +# - employees:read +# - payroll:read (optional) +# - devices:read (optional) +# - apps:read (optional) diff --git a/README.md b/README.md index ef7ddad..7063efb 100644 --- a/README.md +++ b/README.md @@ -10,28 +10,46 @@ **This MCP server gives AI direct access to your entire Rippling workspace.** Instead of clicking through interfaces, you just *tell* it what you need. -### 🎯 Rippling-Native Power Moves +### 🎯 HR & IT Power Moves with Rippling The AI can directly control your Rippling account with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Rippling data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Rippling with other tools seamlessly +1. **New Hire Provisioning** — "Get all employees starting next week, list their assigned devices, check which apps they need access to, and generate IT setup checklists" + +2. **Payroll Intelligence** — "Pull payroll summary for Q1 2026, group by department, identify outliers, and flag any employees with missing tax documents" + +3. **Device Audit** — "List all MacBooks assigned in the last 6 months, show which employees have them, check for missing devices, and generate a replacement schedule" + +4. **Org Structure Analysis** — "Map all departments, teams, and job levels — identify gaps in the reporting structure and suggest reorganization opportunities" + +5. **Leave Management** — "Show all approved leave requests for December, calculate coverage gaps by team, and identify who's available for on-call" ### 🔗 The Real Power: Combining Tools AI can chain multiple Rippling operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query employees → Check device assignments → Provision missing apps +- Pull leave requests → Cross-reference team coverage → Alert managers +- Get payroll data → Match with performance levels → Generate compensation analysis ## 📦 What's Inside -**107 API tools** covering the entire Rippling platform (HR & Payroll). +**12 API tools** covering Rippling HR and IT operations: -All with proper error handling, automatic authentication, and TypeScript types. +- `list_employees` — All employees with employment details and status +- `get_employee` — Detailed employee profile with manager and personal info +- `list_departments` — Department hierarchy and structure +- `list_teams` — Cross-functional teams and groups +- `get_payroll` — Payroll runs and compensation data +- `list_devices` — IT-managed devices (laptops, phones, tablets) +- `list_apps` — Integrated applications and provisioning status +- `get_company` — Company information and settings +- `list_groups` — Custom groups for access control +- `list_levels` — Job levels and career ladders +- `list_work_locations` — Office locations and remote sites +- `get_leave_requests` — PTO and leave requests with status + +All with proper error handling, OAuth authentication, and TypeScript types. ## 🚀 Quick Start @@ -45,7 +63,10 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Rippling API credentials** (see Authentication section below) +2. **Get your Rippling API credentials:** + - Log into Rippling → Settings → Integrations → API + - Create OAuth application or generate API token + - Copy your API key/OAuth token 3. **Configure Claude Desktop:** @@ -58,7 +79,7 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "rippling": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/rippling-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/rippling-mcp-2026-complete/dist/index.js"], "env": { "RIPPLING_API_KEY": "your-api-key-here" } @@ -74,7 +95,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/rippling-mcp) 1. Click the button above -2. Set your Rippling API credentials in Railway dashboard +2. Set `RIPPLING_API_KEY` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -88,19 +109,33 @@ docker run -p 3000:3000 \ ## 🔐 Authentication -See the official [Rippling API documentation](https://docs.rippling.com) for authentication details. +Rippling uses **OAuth 2.0** or **API Token authentication**. -The MCP server handles token refresh automatically. +**Get your API credentials:** +1. Rippling → Settings → Integrations → API +2. Create OAuth app or generate API token +3. Configure required scopes: + - `employees:read` — Employee data access + - `payroll:read` — Payroll data (optional) + - `devices:read` — Device management (optional) + - `apps:read` — App provisioning (optional) + +**API Documentation:** https://developer.rippling.com/docs/rippling-api/ + +The MCP server handles OAuth token refresh automatically. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, you can use natural language. HR/IT-specific examples: -- *"Show me recent activity in Rippling"* -- *"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 active employees in engineering with their device assignments"* +- *"Get pending leave requests for January and check team coverage"* +- *"List all departments and their headcount"* +- *"Pull payroll data for Q4 2025 filtered by department"* +- *"Show me all MacBooks assigned to the product team"* +- *"Get company info and list all work locations"* +- *"Find employees at IC3 level or higher in San Francisco"* +- *"List all apps integrated with Rippling and who has access"* ## 🛠️ Development @@ -132,18 +167,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/OAuth token is correct +- Check that your OAuth scopes include required permissions +- Ensure your API key hasn't expired (OAuth tokens expire) ### "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) +### "Insufficient permissions" +- Review your OAuth scopes in Rippling settings +- Ensure your API token has read access to required resources + ## 📖 Resources -- [Rippling API Documentation](https://docs.rippling.com) +- [Rippling Platform API Documentation](https://developer.rippling.com/docs/rippling-api/) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +202,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 8dac0a2..470c287 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Rippling API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",