CPFHub.io

Look up a Brazilian CPF (name, gender, birth date) and check its registration status and death year at Receita Federal in real time.

View on cpfhub.ioTry this MCPSponsored

Hosted MCP Server

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

Installs into Claude Code, Codex, Cursor and more

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