Rippling MCP Server

Rippling HR/IT/Finance platform integration with 18 tools for managing employees, departments, payroll, benefits, time tracking, and company operations.

GitHub

Rippling MCP Server

npm version License: MIT MCP GitHub

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

ToolDescription
get_companyGet company details (name, address, locations)
list_departmentsList all departments with hierarchy
list_work_locationsList work locations and addresses

Employees

ToolDescription
list_employeesList active employees (paginated)
get_employeeGet a specific employee by ID
list_all_employeesList all employees including terminated
search_employeesSearch by name, email, title, or department

Organization

ToolDescription
list_teamsList teams and subteam relationships
list_levelsList position levels (IC, Manager, Executive)
list_custom_fieldsList custom field definitions

Leave Management

ToolDescription
get_leave_balancesGet PTO/sick leave balances for an employee
list_leave_requestsList leave requests (filter by status, date, requester)
process_leave_requestApprove or decline a pending leave request
list_leave_typesList all leave types configured for the company

Groups

ToolDescription
list_groupsList all groups
create_groupCreate a new group with members
update_groupUpdate group name or members
delete_groupDelete a group

Activity

ToolDescription
get_company_activityGet activity events (hires, changes, terminations)

Configuration

VariableRequiredDefaultDescription
RIPPLING_API_TOKENYes—Your Rippling API token
RIPPLING_BASE_URLNohttps://api.rippling.com/platform/apiAPI 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.

Serveurs connexes