MCP Server

O @cpfhub/mcp é o servidor Model Context Protocol oficial do CPFHub.io. Permite que agentes de IA como Claude, Cursor e outros clientes MCP consultem CPFs diretamente durante conversas.

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 e receber os dados de identidade diretamente na resposta.

Instalação

Não é necessário instalar globalmente - use npx:

bash

npx @cpfhub/mcp

Ou instale globalmente:

bash

npm install -g @cpfhub/mcp

Configuração

O CPFHub.io suporta dois modos de conexão: remoto (recomendado — sem instalação) e local (via npx).

Remoto — HTTP Streamable (recomendado)

Funciona em qualquer cliente MCP que suporte conexões HTTP. Não requer Node.js instalado.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

JSON

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

Claude Code (via terminal):

bash

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

Cursor (.cursor/mcp.json):

JSON

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

Local — stdio via npx

Use quando o cliente MCP não suportar HTTP ou você precisar rodar offline.

Claude Desktop ou Cursor (via npx):

JSON

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

Variável de ambiente (local)

bash

export CPFHUB_API_KEY=sua_api_key_aqui
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 consultas por mês.

Tools disponíveis

`lookup_cpf`

Retorna os dados de identidade de um CPF brasileiro. Consome 1 crédito por consulta encontrada.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`cpf`	`string`	Sim	CPF com ou sem formatação

Resposta:

JSON

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

`get_quota_info`

Retorna os créditos restantes e o status do plano atual. Não consome crédito.

Resposta:

JSON

{
  "plan": "pro",
  "creditsUsed": 234,
  "creditsTotal": 1000,
  "creditsRemaining": 766,
  "resetDate": "2026-06-01"
}

Definição da tool (para uso manual)

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

JSON

{
  "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
npm: @cpfhub/mcp - versões

Atualizado em 16 de junho de 2026