CPFHub.io

Consultez un CPF brésilien (nom, sexe, date de naissance) et vérifiez son statut d'inscription et son année de décès auprès de la Receita Federal en temps réel.

Voir sur cpfhub.io

Serveur MCP hébergé

npx add-mcp 'https://api.cpfhub.io/mcp'

S’installe dans Claude Code, Codex, Cursor et plus

Documentation

MCP Server

O CPFHub.io tem um servidor Model Context Protocol remoto em https://api.cpfhub.io/mcp. Ele permite que agentes de IA como Claude, Cursor e outros clientes MCP consultem CPFs diretamente durante a conversa, sem instalar nada.

O que é o MCP?

O Model Context Protocol (MCP) é um protocolo aberto que permite que LLMs chamem ferramentas externas de forma padronizada. Com o servidor MCP do CPFHub.io, o agente pode chamar lookup_cpf, lookup_cpf_realtime e get_quota_info e receber os dados diretamente na resposta.

Instalação

Use o servidor remoto (https://api.cpfhub.io/mcp), que não exige instalação e tem as três tools. O pacote local npx @cpfhub/mcp existe apenas para clientes sem suporte a HTTP e tem limitações (veja abaixo).

Configuração

O CPFHub.io suporta dois modos de conexão: remoto (recomendado, sem instalação) e local (via npx, alternativa para clientes sem suporte a HTTP).

Remoto: HTTP Streamable (recomendado)

Funciona em qualquer cliente MCP que suporte conexões HTTP (Streamable HTTP). Não requer Node.js instalado. A API Key vai no header x-api-key ou, para clientes que não aceitam headers, na URL como ?api_key=.

Claude Desktop e claude.ai: servidores remotos não entram no claude_desktop_config.json (esse arquivo é só para servidores locais). Adicione como conector:

Abra Configurações > Conectores e clique em Adicionar conector personalizado.
Nome: CPFHub.io. URL: https://api.cpfhub.io/mcp?api_key=SUA_API_KEY.
Salve e ative o conector na conversa. ⚠

A URL contém sua chave

Com ?api_key= na URL, a chave fica salva na configuração do conector. Não compartilhe essa URL nem prints da tela. Se ela vazar, gere uma nova chave em Chaves de API.

Claude Code (via terminal):

claude mcp add cpfhub --transport http https://api.cpfhub.io/mcp --header "x-api-key: $CPFHUB_API_KEY"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cpfhub": {
      "url": "https://api.cpfhub.io/mcp",
      "headers": { "x-api-key": "SUA_API_KEY" }
    }
  }
}

Para testar a conexão e a chave sem gastar créditos, liste as tools com curl:

curl -s https://api.cpfhub.io/mcp \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A resposta deve listar lookup_cpf, lookup_cpf_realtime e get_quota_info.

Local: stdio via npx

Use somente quando o cliente MCP não suportar HTTP. O servidor roda na sua máquina, mas cada consulta chama a API da CPFHub.io, então precisa de internet e de uma API Key.

⚠

Limitações do pacote local

O pacote @cpfhub/mcp tem só lookup_cpf funcionando. A tool get_quota_info não funciona na versão atual do pacote (consulte o saldo via GET /quota), e a lookup_cpf_realtime existe só no servidor remoto. Prefira o remoto sempre que o cliente suportar HTTP.

Claude Desktop ou Cursor (via npx):

{
  "mcpServers": {
    "cpfhub": {
      "command": "npx",
      "args": ["-y", "@cpfhub/mcp"],
      "env": {
        "CPFHUB_API_KEY": "SUA_API_KEY"
      }
    }
  }
}

Variável de ambiente (local)

export CPFHUB_API_KEY=SUA_API_KEY
npx @cpfhub/mcp

✦

Obtenha sua API Key gratuitamente

Crie uma conta em app.cpfhub.io e gere sua chave em Chaves de API. O plano gratuito inclui 50 créditos por mês.

Tools disponíveis

lookup_cpf

Consulta Simples: retorna nome, gênero e data de nascimento a partir da base da CPFHub.io (mesmos dados de GET /cpf/{cpf}). Consome o custo de uma Consulta Simples do seu plano (1 crédito por padrão) por CPF encontrado. CPF não encontrado não consome crédito.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`cpf`	`string`	Sim	CPF com ou sem formatação
`api_key`	`string`	Não	Sua API Key. Opcional quando a chave já foi enviada na conexão (header `x-api-key` ou `?api_key=`)

Resposta (conteúdo de texto da tool, em JSON):

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

Em caso de erro, a tool retorna isError: true e error como string:

{
  "success": false,
  "error": "CPF não encontrado na base de dados"
}

Quando o limite de requisições por minuto é atingido, o erro vem com retry_after (segundos de espera):

{
  "success": false,
  "error": "Limite de requisições por minuto excedido. Tente novamente em 12 segundos.",
  "retry_after": 12
}

lookup_cpf_realtime

Consulta em Tempo Real: consulta a Receita Federal no momento da chamada e retorna nome, data de nascimento, ano do óbito, situação cadastral, código de controle e comprovante (mesmos dados de POST /cpf/realtime). Consome 1,5 crédito por consulta bem-sucedida por padrão; consulte o custo do seu plano no dashboard. O tempo típico é cerca de 1 segundo (não é um SLA). Só no servidor remoto.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`cpf`	`string`	Sim	CPF com ou sem formatação
`birth_date`	`string`	Sim	Data de nascimento do titular, `DD/MM/AAAA` ou `DDMMAAAA`
`api_key`	`string`	Não	Sua API Key. Opcional quando a chave já foi enviada na conexão

Resposta:

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/...",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/..."
  }
}

deathYear sempre vem na resposta como inteiro ou null. É null quando não há óbito registrado ou quando o valor recebido é inválido: precisa ter 4 dígitos, estar entre 1900 e o ano atual e não ser anterior ao ano de nascimento.

Os erros seguem o mesmo formato de lookup_cpf (isError: true, error como string), com as mensagens de POST /cpf/realtime. Data de nascimento divergente e indisponibilidade da Receita Federal não consomem crédito.

get_quota_info

Retorna o plano, os créditos restantes e usados, o status de cobrança e os identificadores da conta. Não consome crédito e funciona mesmo com saldo zerado.

Resposta:

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

billingStatus indica a elegibilidade ao plano: active quando a conta tem uma assinatura que dá acesso ao plano, inclusive assinatura no plano Gratuito e status como past_due; free quando não há assinatura válida, por exemplo canceled, unpaid ou incomplete_expired. Nesse caso, plan pode vir como unknown. Os custos padrão são 1 crédito por Consulta Simples e 1,5 crédito por Consulta em Tempo Real; os custos e as regras de excedente específicas do seu plano ficam no dashboard. Os limites padrão são 30/min na Consulta Simples (cada envio de lote conta como 1) e 5/min na Consulta em Tempo Real. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io. Acima do limite, a API responde 429 com o header Retry-After.

Disponível também via REST: GET /quota, com o mesmo payload.

ℹ

Consulta em lote só via REST

Não há tool de lote no MCP. Para consultar muitos CPFs, use a consulta em lote (POST /cpf/bulk) via REST.

Definição da tool (para uso manual)

Se quiser usar a tool em prompts de sistema sem o servidor MCP:

{
  "name": "lookup_cpf",
  "description": "Retrieve identity data (full name, gender, date of birth) from a Brazilian CPF number using the CPFHub.io API",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)"
      }
    },
    "required": ["cpf"]
  }
}

Exemplo de uso no Claude

Com o servidor MCP configurado, você pode simplesmente pedir ao Claude:

"Valide o CPF 123.456.789-09 e me diga o nome e a data de nascimento do titular."

O Claude chamará automaticamente lookup_cpf e incluirá os dados na resposta.

Repositório

github.com/cpfhub/cpfhub-mcp: código-fonte e issues do pacote local
npm: @cpfhub/mcp: versões do pacote local

Atualizado em 4 de outubro de 2026