io.github.cpfhub/cpfhub

cpfhub-mcp: Official MCP Server for CPFHub.io

🇺🇸 English | 🇧🇷 Português

Official Model Context Protocol (MCP) server for CPFHub.io — Brazilian CPF Lookup API for AI agents.

---

What is CPFHub.io?

CPFHub.io is a REST API that returns identity data — full name, gender, and date of birth — from any Brazilian CPF number, in ~300ms, with 99.9% uptime and full LGPD compliance.

10M+ CPFs queried · 1,300+ active companies · 99.9% uptime

---

Tools

This MCP server exposes the following tools:

Tool	Description
get_person_by_cpf	Retrieve identity data (full name, gender, date of birth) from a Brazilian CPF number
get_quota_information	Retrieve remaining API credits and current plan status

Tool Definition

{
  "name": "get_person_by_cpf",
  "description": "Retrieve identity data from a Brazilian CPF number",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)"
      }
    },
    "required": ["cpf"]
  }
}

---

Quick Start

# Set your API key
export CPFHUB_API_KEY=your_api_key_here

# Run the MCP server directly with npx (no install needed)
npx @cpfhub/mcp

Get your free API key at app.cpfhub.io — no credit card required.

---

curl Example

curl -X GET "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "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
  }
}

---

Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

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

Cursor

1. Go to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Name: CPFHub
4. Type: command
5. Command: export CPFHUB_API_KEY=YOUR_API_KEY_HERE && npx -y @cpfhub/mcp

Windsurf

Add to your MCP configuration file:

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

---

OpenAI Function Calling Example

import os
import json
import requests
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
CPFHUB_API_KEY = os.environ["CPFHUB_API_KEY"]

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_person_by_cpf",
            "description": "Retrieve identity data from a Brazilian CPF number",
            "parameters": {
                "type": "object",
                "properties": {
                    "cpf": {"type": "string", "description": "Brazilian CPF number"}
                },
                "required": ["cpf"],
            },
        },
    }
]

def get_person_by_cpf(cpf: str) -> dict:
    response = requests.get(
        f"https://api.cpfhub.io/cpf/{cpf.replace('.', '').replace('-', '')}",
        headers={"x-api-key": CPFHUB_API_KEY},
    )
    return response.json()

messages = [{"role": "user", "content": "Who is the person with CPF 123.456.789-09?"}]
response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
message = response.choices[0].message

if message.tool_calls:
    args = json.loads(message.tool_calls[0].function.arguments)
    result = get_person_by_cpf(args["cpf"])
    print(result)

---

LangChain Example

See examples/langchain_example.py for a full LangChain agent integration example.

---

Requirements

• Node.js 18 or higher
• A valid API key from app.cpfhub.io

---

Links

Resource	URL
Documentation	https://cpfhub.io/documentacao
Dashboard	https://app.cpfhub.io
OpenAPI Specification	https://github.com/cpfhub/cpfhub-openapi
Node.js SDK	https://github.com/cpfhub/cpfhub-node
Python SDK	https://github.com/cpfhub/cpfhub-python
All SDKs	https://github.com/cpfhub

---

License

MIT © CPFHub.io

---

Português

🇺🇸 English | 🇧🇷 Português

Servidor Model Context Protocol (MCP) oficial para CPFHub.io — API de Consulta de CPF Brasileiro para agentes de IA.

---

O que é o CPFHub.io?

O CPFHub.io é uma API REST que retorna dados de identidade — nome completo, gênero e data de nascimento — de qualquer CPF brasileiro, em ~300ms, com 99,9% de uptime e total conformidade com a LGPD.

10M+ CPFs consultados · 1.300+ empresas ativas · 99,9% uptime

---

Ferramentas (Tools)

Este servidor MCP expõe as seguintes ferramentas:

Ferramenta	Descrição
get_person_by_cpf	Recupera dados de identidade (nome completo, gênero, data de nascimento) a partir de um CPF brasileiro
get_quota_information	Recupera os créditos de API restantes e o status do plano atual

Definição da Ferramenta

{
  "name": "get_person_by_cpf",
  "description": "Retrieve identity data from a Brazilian CPF number",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)"
      }
    },
    "required": ["cpf"]
  }
}

---

Início Rápido

# Configure sua chave de API
export CPFHUB_API_KEY=sua_chave_de_api_aqui

# Execute o servidor MCP diretamente com npx (sem instalação)
npx @cpfhub/mcp

Obtenha sua chave de API gratuita em app.cpfhub.io — sem cartão de crédito.

---

Exemplo curl

curl -X GET "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: SUA_CHAVE_DE_API"

Resposta:

{
  "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
  }
}

---

Configuração

Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

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

Cursor

1. Acesse Settings > Features > MCP.
2. Clique em + Add New MCP Server.
3. Nome: CPFHub
4. Tipo: command
5. Comando: export CPFHUB_API_KEY=SUA_CHAVE_DE_API_AQUI && npx -y @cpfhub/mcp

Windsurf

Adicione ao seu arquivo de configuração MCP:

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

---

Exemplo com OpenAI Function Calling

import os
import json
import requests
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
CPFHUB_API_KEY = os.environ["CPFHUB_API_KEY"]

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_person_by_cpf",
            "description": "Retrieve identity data from a Brazilian CPF number",
            "parameters": {
                "type": "object",
                "properties": {
                    "cpf": {"type": "string", "description": "Brazilian CPF number"}
                },
                "required": ["cpf"],
            },
        },
    }
]

def get_person_by_cpf(cpf: str) -> dict:
    response = requests.get(
        f"https://api.cpfhub.io/cpf/{cpf.replace('.', '').replace('-', '')}",
        headers={"x-api-key": CPFHUB_API_KEY},
    )
    return response.json()

messages = [{"role": "user", "content": "Quem é a pessoa com CPF 123.456.789-09?"}]
response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
message = response.choices[0].message

if message.tool_calls:
    args = json.loads(message.tool_calls[0].function.arguments)
    result = get_person_by_cpf(args["cpf"])
    print(result)

---

Exemplo com LangChain

Veja examples/langchain_example.py para um exemplo completo de integração com agente LangChain.

---

Requisitos

• Node.js 18 ou superior
• Uma chave de API válida de app.cpfhub.io

---

Links

Recurso	URL
Documentação	https://cpfhub.io/documentacao
Dashboard	https://app.cpfhub.io
Especificação OpenAPI	https://github.com/cpfhub/cpfhub-openapi
SDK Node.js	https://github.com/cpfhub/cpfhub-node
SDK Python	https://github.com/cpfhub/cpfhub-python
Todos os SDKs	https://github.com/cpfhub

---

Licença

MIT © CPFHub.io