rippling-mcp-server

MCP server for Rippling — HR, payroll, and workforce management.

Tools

Tool	Description
search_workers	Search workers by name or email. Returns shaped results with name, title, department, manager, location, compensation
get_headcount_snapshot	Headcount by department and location, employment type breakdown, recent hires and departures (30-day window)
get_compensation_summary	Total cash comp (salary + bonus + commission) aggregated by department with min/max/avg ranges
get_org_structure	Department hierarchy tree, teams, resolved manager names, direct report counts
get_worker_details	Full worker profile: name, email, title, department, teams, manager, start date, compensation, level, location

Installation

No install needed — runs directly via npx:

npx -y github:rocketsciencegg/rippling-mcp-server

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rippling": {
      "command": "npx",
      "args": ["-y", "github:rocketsciencegg/rippling-mcp-server"],
      "env": {
        "RIPPLING_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "rippling": {
      "command": "npx",
      "args": ["-y", "github:rocketsciencegg/rippling-mcp-server"],
      "env": {
        "RIPPLING_API_KEY": "${RIPPLING_API_KEY}"
      }
    }
  }
}

Remote (HTTP mode)

Set the PORT environment variable to start the server in HTTP mode:

PORT=3000 RIPPLING_API_KEY=your-api-key npx -y github:rocketsciencegg/rippling-mcp-server

The MCP endpoint will be available at http://0.0.0.0:3000/mcp.

Environment Variables

Variable	Description
RIPPLING_API_KEY	Your Rippling API key
PORT	(Optional) Start in HTTP mode on this port instead of STDIO

Features

• Cursor-based pagination — fetches all records across pages
• Graceful compensation scope fallback — tools work even without the compensation OAuth scope
• 429 rate limit retry with exponential backoff and Retry-After support
• Worker names resolved via Rippling user expansion
• Locations resolved via WorkLocations API
• Manager names resolved across paginated results
• Dual transport: STDIO (default) or HTTP for remote hosting

Development

git clone https://github.com/rocketsciencegg/rippling-mcp-server.git
cd rippling-mcp-server
npm install
npm run build
npm test

Integration tests

Requires a RIPPLING_API_KEY (not run in CI):

RIPPLING_API_KEY=your-key just integration

License

MIT