Rippling MCP Server

An open-source Model Context Protocol (MCP) server for the Rippling 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:

{
  "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

# 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 (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.