{
  "markdown": "# cpfhub-mcp: Official MCP Server for CPFHub.io\n\n🇺🇸 **English** | [🇧🇷 Português](#português)\n\n**Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [CPFHub.io](https://cpfhub.io) — Brazilian CPF Lookup API for AI agents.**\n\n[![npm version](https://img.shields.io/npm/v/@cpfhub/mcp)](https://www.npmjs.com/package/@cpfhub/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## What is CPFHub.io?\n\nCPFHub.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.\n\n**10M+ CPFs queried · 1,300+ active companies · 99.9% uptime**\n\n---\n\n## Tools\n\nThis MCP server exposes the following tools:\n\n| Tool | Description |\n| :--- | :--- |\n| `get_person_by_cpf` | Retrieve identity data (full name, gender, date of birth) from a Brazilian CPF number |\n| `get_quota_information` | Retrieve remaining API credits and current plan status |\n\n### Tool Definition\n\n```json\n{\n  \"name\": \"get_person_by_cpf\",\n  \"description\": \"Retrieve identity data from a Brazilian CPF number\",\n  \"parameters\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"cpf\": {\n        \"type\": \"string\",\n        \"description\": \"Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)\"\n      }\n    },\n    \"required\": [\"cpf\"]\n  }\n}\n```\n\n---\n\n## Quick Start\n\n```bash\n# Set your API key\nexport CPFHUB_API_KEY=your_api_key_here\n\n# Run the MCP server directly with npx (no install needed)\nnpx @cpfhub/mcp\n```\n\nGet your free API key at [app.cpfhub.io](https://app.cpfhub.io) — no credit card required.\n\n---\n\n## curl Example\n\n```bash\ncurl -X GET \"https://api.cpfhub.io/cpf/12345678909\" \\\n  -H \"x-api-key: YOUR_API_KEY\"\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"cpf\": \"12345678909\",\n    \"name\": \"Fulano de Tal\",\n    \"nameUpper\": \"FULANO DE TAL\",\n    \"gender\": \"M\",\n    \"birthDate\": \"15/06/1990\",\n    \"day\": 15,\n    \"month\": 6,\n    \"year\": 1990\n  }\n}\n```\n\n---\n\n## Configuration\n\n### Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cpfhub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cpfhub/mcp\"],\n      \"env\": {\n        \"CPFHUB_API_KEY\": \"YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\n1. Go to **Settings** > **Features** > **MCP**.\n2. Click **+ Add New MCP Server**.\n3. Name: `CPFHub`\n4. Type: `command`\n5. Command: `export CPFHUB_API_KEY=YOUR_API_KEY_HERE && npx -y @cpfhub/mcp`\n\n### Windsurf\n\nAdd to your MCP configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"cpfhub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cpfhub/mcp\"],\n      \"env\": {\n        \"CPFHUB_API_KEY\": \"YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## OpenAI Function Calling Example\n\n```python\nimport os\nimport json\nimport requests\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"OPENAI_API_KEY\"])\nCPFHUB_API_KEY = os.environ[\"CPFHUB_API_KEY\"]\n\ntools = [\n    {\n        \"type\": \"function\",\n        \"function\": {\n            \"name\": \"get_person_by_cpf\",\n            \"description\": \"Retrieve identity data from a Brazilian CPF number\",\n            \"parameters\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"cpf\": {\"type\": \"string\", \"description\": \"Brazilian CPF number\"}\n                },\n                \"required\": [\"cpf\"],\n            },\n        },\n    }\n]\n\ndef get_person_by_cpf(cpf: str) -> dict:\n    response = requests.get(\n        f\"https://api.cpfhub.io/cpf/{cpf.replace('.', '').replace('-', '')}\",\n        headers={\"x-api-key\": CPFHUB_API_KEY},\n    )\n    return response.json()\n\nmessages = [{\"role\": \"user\", \"content\": \"Who is the person with CPF 123.456.789-09?\"}]\nresponse = client.chat.completions.create(model=\"gpt-4o\", messages=messages, tools=tools)\nmessage = response.choices[0].message\n\nif message.tool_calls:\n    args = json.loads(message.tool_calls[0].function.arguments)\n    result = get_person_by_cpf(args[\"cpf\"])\n    print(result)\n```\n\n---\n\n## LangChain Example\n\nSee [`examples/langchain_example.py`](examples/langchain_example.py) for a full LangChain agent integration example.\n\n---\n\n## Requirements\n\n- Node.js 18 or higher\n- A valid API key from [app.cpfhub.io](https://app.cpfhub.io)\n\n---\n\n## Links\n\n| Resource | URL |\n| :--- | :--- |\n| Documentation | [https://cpfhub.io/documentacao](https://cpfhub.io/documentacao) |\n| Dashboard | [https://app.cpfhub.io](https://app.cpfhub.io) |\n| OpenAPI Specification | [https://github.com/cpfhub/cpfhub-openapi](https://github.com/cpfhub/cpfhub-openapi) |\n| Node.js SDK | [https://github.com/cpfhub/cpfhub-node](https://github.com/cpfhub/cpfhub-node) |\n| Python SDK | [https://github.com/cpfhub/cpfhub-python](https://github.com/cpfhub/cpfhub-python) |\n| All SDKs | [https://github.com/cpfhub](https://github.com/cpfhub) |\n\n---\n\n## License\n\nMIT © [CPFHub.io](https://cpfhub.io)\n\n---\n\n# Português\n\n[🇺🇸 English](#cpfhub-mcp-official-mcp-server-for-cpfhubio) | 🇧🇷 **Português**\n\n**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.**\n\n---\n\n## O que é o CPFHub.io?\n\nO 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.\n\n**10M+ CPFs consultados · 1.300+ empresas ativas · 99,9% uptime**\n\n---\n\n## Ferramentas (Tools)\n\nEste servidor MCP expõe as seguintes ferramentas:\n\n| Ferramenta | Descrição |\n| :--- | :--- |\n| `get_person_by_cpf` | Recupera dados de identidade (nome completo, gênero, data de nascimento) a partir de um CPF brasileiro |\n| `get_quota_information` | Recupera os créditos de API restantes e o status do plano atual |\n\n### Definição da Ferramenta\n\n```json\n{\n  \"name\": \"get_person_by_cpf\",\n  \"description\": \"Retrieve identity data from a Brazilian CPF number\",\n  \"parameters\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"cpf\": {\n        \"type\": \"string\",\n        \"description\": \"Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)\"\n      }\n    },\n    \"required\": [\"cpf\"]\n  }\n}\n```\n\n---\n\n## Início Rápido\n\n```bash\n# Configure sua chave de API\nexport CPFHUB_API_KEY=sua_chave_de_api_aqui\n\n# Execute o servidor MCP diretamente com npx (sem instalação)\nnpx @cpfhub/mcp\n```\n\nObtenha sua chave de API gratuita em [app.cpfhub.io](https://app.cpfhub.io) — sem cartão de crédito.\n\n---\n\n## Exemplo curl\n\n```bash\ncurl -X GET \"https://api.cpfhub.io/cpf/12345678909\" \\\n  -H \"x-api-key: SUA_CHAVE_DE_API\"\n```\n\n**Resposta:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"cpf\": \"12345678909\",\n    \"name\": \"Fulano de Tal\",\n    \"nameUpper\": \"FULANO DE TAL\",\n    \"gender\": \"M\",\n    \"birthDate\": \"15/06/1990\",\n    \"day\": 15,\n    \"month\": 6,\n    \"year\": 1990\n  }\n}\n```\n\n---\n\n## Configuração\n\n### Claude Desktop\n\nAdicione o seguinte ao seu `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cpfhub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cpfhub/mcp\"],\n      \"env\": {\n        \"CPFHUB_API_KEY\": \"SUA_CHAVE_DE_API_AQUI\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\n1. Acesse **Settings** > **Features** > **MCP**.\n2. Clique em **+ Add New MCP Server**.\n3. Nome: `CPFHub`\n4. Tipo: `command`\n5. Comando: `export CPFHUB_API_KEY=SUA_CHAVE_DE_API_AQUI && npx -y @cpfhub/mcp`\n\n### Windsurf\n\nAdicione ao seu arquivo de configuração MCP:\n\n```json\n{\n  \"mcpServers\": {\n    \"cpfhub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cpfhub/mcp\"],\n      \"env\": {\n        \"CPFHUB_API_KEY\": \"SUA_CHAVE_DE_API_AQUI\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Exemplo com OpenAI Function Calling\n\n```python\nimport os\nimport json\nimport requests\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=os.environ[\"OPENAI_API_KEY\"])\nCPFHUB_API_KEY = os.environ[\"CPFHUB_API_KEY\"]\n\ntools = [\n    {\n        \"type\": \"function\",\n        \"function\": {\n            \"name\": \"get_person_by_cpf\",\n            \"description\": \"Retrieve identity data from a Brazilian CPF number\",\n            \"parameters\": {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"cpf\": {\"type\": \"string\", \"description\": \"Brazilian CPF number\"}\n                },\n                \"required\": [\"cpf\"],\n            },\n        },\n    }\n]\n\ndef get_person_by_cpf(cpf: str) -> dict:\n    response = requests.get(\n        f\"https://api.cpfhub.io/cpf/{cpf.replace('.', '').replace('-', '')}\",\n        headers={\"x-api-key\": CPFHUB_API_KEY},\n    )\n    return response.json()\n\nmessages = [{\"role\": \"user\", \"content\": \"Quem é a pessoa com CPF 123.456.789-09?\"}]\nresponse = client.chat.completions.create(model=\"gpt-4o\", messages=messages, tools=tools)\nmessage = response.choices[0].message\n\nif message.tool_calls:\n    args = json.loads(message.tool_calls[0].function.arguments)\n    result = get_person_by_cpf(args[\"cpf\"])\n    print(result)\n```\n\n---\n\n## Exemplo com LangChain\n\nVeja [`examples/langchain_example.py`](examples/langchain_example.py) para um exemplo completo de integração com agente LangChain.\n\n---\n\n## Requisitos\n\n- Node.js 18 ou superior\n- Uma chave de API válida de [app.cpfhub.io](https://app.cpfhub.io)\n\n---\n\n## Links\n\n| Recurso | URL |\n| :--- | :--- |\n| Documentação | [https://cpfhub.io/documentacao](https://cpfhub.io/documentacao) |\n| Dashboard | [https://app.cpfhub.io](https://app.cpfhub.io) |\n| Especificação OpenAPI | [https://github.com/cpfhub/cpfhub-openapi](https://github.com/cpfhub/cpfhub-openapi) |\n| SDK Node.js | [https://github.com/cpfhub/cpfhub-node](https://github.com/cpfhub/cpfhub-node) |\n| SDK Python | [https://github.com/cpfhub/cpfhub-python](https://github.com/cpfhub/cpfhub-python) |\n| Todos os SDKs | [https://github.com/cpfhub](https://github.com/cpfhub) |\n\n---\n\n## Licença\n\nMIT © [CPFHub.io](https://cpfhub.io)\n",
  "bytes": 9880,
  "sha": "bbc0d184e3ad64f9f40a0f42dd9af641d4353d6343a3277181a5764742ac0aed",
  "repo_slug": "cpfhub/cpfhub-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cpfhub_cpfhub_ed49981f/readme"
}