# Rippling MCP Server

MCP server for [Rippling](https://www.rippling.com/) API integration. Access employees, departments, teams, payroll, devices, and apps for HR and IT management.

## Setup

```bash
npm install
npm run build
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `RIPPLING_API_KEY` | Yes | Bearer API key or OAuth access token |

## API Endpoint

- **Base URL:** `https://api.rippling.com/platform/api`

## Tools

### HR / People
- **list_employees** - List employees with pagination and terminated filter
- **get_employee** - Get detailed employee information
- **list_departments** - List all departments
- **list_teams** - List all teams
- **list_levels** - List job levels (IC1, Manager, etc.)
- **list_work_locations** - List office locations
- **get_leave_requests** - Get time-off/leave requests

### Payroll
- **get_payroll** - Get payroll runs and compensation data

### IT
- **list_devices** - List managed devices (laptops, phones)
- **list_apps** - List integrated applications

### Company
- **get_company** - Get company information
- **list_groups** - List custom groups for access control

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rippling": {
      "command": "node",
      "args": ["/path/to/mcp-servers/rippling/dist/index.js"],
      "env": {
        "RIPPLING_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Authentication

Rippling supports two authentication methods:

### Bearer API Key
Generate an API key in your Rippling admin settings for server-to-server integrations.

### OAuth 2.0
For partner integrations, use OAuth flow:
1. Register as a Rippling partner
2. Implement OAuth installation flow
3. Exchange authorization code for access token

See [Rippling Developer Docs](https://developer.rippling.com/documentation) for details.

## Required Scopes

Depending on which tools you use, request appropriate scopes:
- `employee:read` - List/get employees
- `department:read` - List departments
- `team:read` - List teams
- `payroll:read` - Access payroll data
- `device:read` - List devices
- `app:read` - List apps
- `company:read` - Company info
- `leave:read` - Leave requests

## Examples

List active employees:
```
list_employees(limit: 50)
```

List all employees including terminated:
```
list_employees(include_terminated: true, limit: 100)
```

Get employee details:
```
get_employee(employee_id: "emp_abc123")
```

List engineering department devices:
```
list_devices(device_type: "laptop", limit: 50)
```

Get pending leave requests:
```
get_leave_requests(status: "pending")
```

Get payroll for date range:
```
get_payroll(start_date: "2024-01-01", end_date: "2024-01-31")
```