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

Para o modo local, 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. A API Key vai no header x-api-key (ou na URL, como ?api_key=, para clientes que não aceitam headers).

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. 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.

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 créditos por mês.

Tools disponíveis

`lookup_cpf`

Retorna os dados de identidade de um CPF brasileiro, 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 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):

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:

JSON

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

`get_quota_info`

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

Resposta:

JSON

{
  "success": true,
  "data": {
    "plan": "Professional",
    "remainingCredits": 4500,
    "usedCredits": 500,
    "staticCreditCost": 1,
    "realtimeCreditCost": 1.5,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

billingStatus é active ou free. staticCreditCost e realtimeCreditCost são os custos por consulta simples e em tempo real no seu plano.

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

ℹ

Consulta em tempo real só via REST

A consulta em tempo real na Receita Federal não é uma tool do MCP. Para usá-la em um agente, chame POST https://api.cpfhub.io/cpf/realtime via REST.

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 2 de outubro de 2026