# Rippling MCP Server
[](https://www.npmjs.com/package/rippling-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://github.com/bifrost-mcp/rippling-mcp)
An open-source [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [Rippling](https://www.rippling.com/) HR/IT/Finance platform. Connect any AI agent or LLM to your Rippling workspace — query employees, manage leave requests, view company structure, and more.
## Features
- **18 tools** across 6 domains: Company, Employees, Organization, Leave, Groups, Activity
- **Bearer token auth** — simple API token setup, no OAuth dance required
- **Rate limit aware** — respects Rippling's rate limit headers
- **AI-friendly errors** — structured error messages with actionable fix suggestions
- **TypeScript** — full type safety, built with `@modelcontextprotocol/sdk`
## Quick Start
### 1. Get a Rippling API Token
Go to **Rippling** > **Settings** > **API Tokens** > **Create API Token**. Copy the token.
### 2. Configure in Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"rippling": {
"command": "npx",
"args": ["-y", "rippling-mcp-server"],
"env": {
"RIPPLING_API_TOKEN": "your_api_token_here"
}
}
}
}
```
### 3. Use It
Ask Claude things like:
- "List all employees in Engineering"
- "Who has pending leave requests?"
- "Show me the company org structure"
- "What's Alice's PTO balance?"
## Tools Reference
### Company
| Tool | Description |
|------|-------------|
| `get_company` | Get company details (name, address, locations) |
| `list_departments` | List all departments with hierarchy |
| `list_work_locations` | List work locations and addresses |
### Employees
| Tool | Description |
|------|-------------|
| `list_employees` | List active employees (paginated) |
| `get_employee` | Get a specific employee by ID |
| `list_all_employees` | List all employees including terminated |
| `search_employees` | Search by name, email, title, or department |
### Organization
| Tool | Description |
|------|-------------|
| `list_teams` | List teams and subteam relationships |
| `list_levels` | List position levels (IC, Manager, Executive) |
| `list_custom_fields` | List custom field definitions |
### Leave Management
| Tool | Description |
|------|-------------|
| `get_leave_balances` | Get PTO/sick leave balances for an employee |
| `list_leave_requests` | List leave requests (filter by status, date, requester) |
| `process_leave_request` | Approve or decline a pending leave request |
| `list_leave_types` | List all leave types configured for the company |
### Groups
| Tool | Description |
|------|-------------|
| `list_groups` | List all groups |
| `create_group` | Create a new group with members |
| `update_group` | Update group name or members |
| `delete_group` | Delete a group |
### Activity
| Tool | Description |
|------|-------------|
| `get_company_activity` | Get activity events (hires, changes, terminations) |
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `RIPPLING_API_TOKEN` | Yes | — | Your Rippling API token |
| `RIPPLING_BASE_URL` | No | `https://api.rippling.com/platform/api` | API base URL |
For sandbox/testing, set `RIPPLING_BASE_URL` to `https://sandbox.rippling.com/api/platform/api`.
## Development
```bash
# Install dependencies
npm install
# Run in development mode
RIPPLING_API_TOKEN=your_token npm run dev
# Run tests
npm test
# Build for production
npm run build
# Type check
npm run lint
```
## How It Works
This server wraps the [Rippling Platform API](https://developer.rippling.com/) (V1) and exposes it through the Model Context Protocol. When an AI agent calls a tool, the server:
1. Validates the input using Zod schemas
2. Makes authenticated requests to the Rippling API
3. Handles rate limiting automatically
4. Returns structured JSON responses (or actionable error messages)
## Limitations
- Employee endpoints are **read-only** (Rippling API V1 restriction)
- API token permissions determine which fields are returned per employee
- Rate limits are enforced by Rippling (monitor via response headers)
- Leave request processing requires appropriate admin permissions
## License
MIT
## Contributing
Issues and PRs welcome.
