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
- Go to Settings > Features > MCP.
- Click + Add New MCP Server.
- Name:
CPFHub - Type:
command - 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
- Acesse Settings > Features > MCP.
- Clique em + Add New MCP Server.
- Nome:
CPFHub - Tipo:
command - 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