# Rippling MCP Server

[![npm version](https://img.shields.io/npm/v/rippling-mcp-server)](https://www.npmjs.com/package/rippling-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![GitHub](https://img.shields.io/github/stars/bifrost-mcp/rippling-mcp)](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.