io.github.cpfhub/cpfhub MCP Server

This MCP server provides access for AI agents to CPFHub.io, a Brazilian CPF lookup REST API. It queries Brazilian CPF data and returns identity information such as full name, gender, and date of birth, enabling agent workflows that need structured personal data from the API.

🛠️ Key Features

Official Model Context Protocol (MCP) server for CPFHub.io
Query Brazilian CPF data directly from AI agents
Uses a REST API that returns identity data (full name, gender, date of birth)

🚀 Use Cases

AI agent identity lookups using CPF values
Agent-assisted workflows that require structured CPF-derived identity fields

⚡ Developer Benefits

MCP integration for CPFHub.io via a dedicated server
Developer-facing package publishing (npm badge shown for @cpfhub/mcp)
MIT-licensed source is referenced (MIT license badge shown)

⚠️ Limitations

Description provided only states identity lookup outputs; no additional tools, authentication, rate limits, or schema details are included in the available source excerpt.

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

json

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

bash

# 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

bash

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

Response:

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

Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

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:

json

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

OpenAI Function Calling Example

python

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

json

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

bash

# 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

bash

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

Resposta:

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

Configuração

Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

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:

json

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

Exemplo com OpenAI Function Calling

python

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

io.github.cpfhub/cpfhub

io.github.cpfhub/cpfhub MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

cpfhub-mcp: Official MCP Server for CPFHub.io

What is CPFHub.io?

Tools

Tool Definition

Quick Start

curl Example

Configuration

Claude Desktop

Cursor

Windsurf

OpenAI Function Calling Example

LangChain Example

Requirements

Links

License

Português

O que é o CPFHub.io?

Ferramentas (Tools)

Definição da Ferramenta

Início Rápido

Exemplo curl

Configuração

Claude Desktop

Cursor

Windsurf

Exemplo com OpenAI Function Calling

Exemplo com LangChain

Requisitos

Links

Licença

Install

Configuration

Related servers