CPFHub MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

cpfhub-mcp

README.md

# cpfhub-mcp: Official MCP Server for CPFHub.io

🇺🇸 **English** | [🇧🇷 Português](#português)

**Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [CPFHub.io](https://cpfhub.io) — Brazilian CPF Lookup API for AI agents.**

[![npm version](https://img.shields.io/npm/v/@cpfhub/mcp)](https://www.npmjs.com/package/@cpfhub/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## 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](https://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

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:

```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`](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](https://app.cpfhub.io)

---

## Links

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

---

## License

MIT © [CPFHub.io](https://cpfhub.io)

---

# Português

[🇺🇸 English](#cpfhub-mcp-official-mcp-server-for-cpfhubio) | 🇧🇷 **Português**

**Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) oficial para [CPFHub.io](https://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](https://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

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:

```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`](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](https://app.cpfhub.io)

---

## Links

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

---

## Licença

MIT © [CPFHub.io](https://cpfhub.io)

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-07-28 14:40 across 2 tools

Disambiguation5/5

The two tools serve completely different purposes: one retrieves personal data from a CPF, the other checks API quota. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern using snake_case (get_person_by_cpf, get_quota_information). The naming is clear and predictable.

Tool Count3/5

With only 2 tools, the server feels thin for a service called 'CPFHub', which implies a broader range of CPF-related operations. However, the tools are focused and may be sufficient for a narrow use case.

Completeness3/5

The server provides only one data retrieval tool for CPF lookup and a quota tool. Missing operations like CPF validation or list/update functions are notable gaps for a CPF-focused server, but the core lookup is covered.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers