Rippling MCP Server

Rippling MCP Server

Um servidor Model Context Protocol (MCP) de código aberto para a plataforma Rippling de RH/TI/Finanças. Conecte qualquer agente de IA ou LLM ao seu workspace Rippling — consulte funcionários, gerencie solicitações de licença, visualize a estrutura da empresa e muito mais.

Recursos

• 18 ferramentas em 6 domínios: Empresa, Funcionários, Organização, Licenças, Grupos, Atividade
• Autenticação por token Bearer — configuração simples de token de API, sem necessidade de fluxo OAuth
• Ciente de limites de taxa — respeita os cabeçalhos de limite de taxa da Rippling
• Erros amigáveis para IA — mensagens de erro estruturadas com sugestões de correção acionáveis
• TypeScript — segurança total de tipos, construído com @modelcontextprotocol/sdk

Início Rápido

1. Obtenha um token de API da Rippling

Vá para Rippling > Configurações > Tokens de API > Criar token de API. Copie o token.

2. Configure no Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "rippling": {
      "command": "npx",
      "args": ["-y", "rippling-mcp-server"],
      "env": {
        "RIPPLING_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

3. Use

Pergunte a Claude coisas como:

• "Liste todos os funcionários da Engenharia"
• "Quem tem solicitações de licença pendentes?"
• "Mostre-me a estrutura organizacional da empresa"
• "Qual é o saldo de PTO da Alice?"

Referência de Ferramentas

Empresa

Ferramenta	Descrição
get_company	Obter detalhes da empresa (nome, endereço, locais)
list_departments	Listar todos os departamentos com hierarquia
list_work_locations	Listar locais de trabalho e endereços

Funcionários

Ferramenta	Descrição
list_employees	Listar funcionários ativos (paginado)
get_employee	Obter um funcionário específico por ID
list_all_employees	Listar todos os funcionários, incluindo desligados
search_employees	Pesquisar por nome, e-mail, cargo ou departamento

Organização

Ferramenta	Descrição
list_teams	Listar equipes e relacionamentos de subequipes
list_levels	Listar níveis de posição (IC, Gerente, Executivo)
list_custom_fields	Listar definições de campos personalizados

Gerenciamento de Licenças

Ferramenta	Descrição
get_leave_balances	Obter saldos de PTO/licença médica de um funcionário
list_leave_requests	Listar solicitações de licença (filtrar por status, data, solicitante)
process_leave_request	Aprovar ou recusar uma solicitação de licença pendente
list_leave_types	Listar todos os tipos de licença configurados para a empresa

Grupos

Ferramenta	Descrição
list_groups	Listar todos os grupos
create_group	Criar um novo grupo com membros
update_group	Atualizar nome do grupo ou membros
delete_group	Excluir um grupo

Atividade

Ferramenta	Descrição
get_company_activity	Obter eventos de atividade (contratações, alterações, desligamentos)

Configuração

Variável	Obrigatório	Padrão	Descrição
RIPPLING_API_TOKEN	Sim	—	Seu token de API da Rippling
RIPPLING_BASE_URL	Não	https://api.rippling.com/platform/api	URL base da API

Para sandbox/testes, defina RIPPLING_BASE_URL como https://sandbox.rippling.com/api/platform/api.

Desenvolvimento

# 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

Como Funciona

Este servidor encapsula a API da Plataforma Rippling (V1) e a expõe por meio do Model Context Protocol. Quando um agente de IA chama uma ferramenta, o servidor:

1. Valida a entrada usando esquemas Zod
2. Faz solicitações autenticadas à API da Rippling
3. Lida com limites de taxa automaticamente
4. Retorna respostas JSON estruturadas (ou mensagens de erro acionáveis)

Limitações

• Os endpoints de funcionários são somente leitura (restrição da API V1 da Rippling)
• As permissões do token de API determinam quais campos são retornados por funcionário
• Os limites de taxa são aplicados pela Rippling (monitore por meio dos cabeçalhos de resposta)
• O processamento de solicitações de licença requer permissões de administrador apropriadas

Licença

MIT

Contribuindo

Issues e PRs são bem-vindos.