MCP Server

CPFHub.io 提供远程 Model Context Protocol 服务器，地址为 https://api.cpfhub.io/mcp。借助它，Claude、Cursor 等 AI 智能体和其他 MCP 客户端可以在对话中查询 CPF（巴西个人税号）和 CNPJ（巴西企业税号）、执行批量查询并创建身份验证，无需安装任何东西。

什么是 MCP？

Model Context Protocol（MCP）是一个开放协议，让 LLM 以标准方式调用外部工具。通过 CPFHub.io MCP 服务器，智能体可以调用下面列出的九个工具，并在回答中直接获得数据。

安装

请使用远程服务器（https://api.cpfhub.io/mcp），它无需安装且包含全部工具。本地包 npx @cpfhub/mcp 仅面向不支持 HTTP 的客户端，并且存在限制（见下文）。

配置

CPFHub.io 支持两种连接方式：远程（推荐，无需安装）和本地（通过 npx，供不支持 HTTP 的客户端使用）。

远程：Streamable HTTP（推荐）

适用于任何支持 HTTP 连接（Streamable HTTP）的 MCP 客户端，不需要 Node.js。API 密钥放在 x-api-key 请求头中。对于不支持请求头的客户端，可以通过 URL 参数 ?api_key= 传递。

Claude Desktop 和 claude.ai：远程服务器不写在 claude_desktop_config.json 中（该文件只用于本地服务器）。请将其添加为连接器：

打开 Settings > Connectors，点击 Add custom connector。
名称：CPFHub.io。URL：https://api.cpfhub.io/mcp?api_key=YOUR_API_KEY。
保存，并在对话中启用该连接器。

⚠

URL 中包含您的密钥

URL 中带有 ?api_key= 时，密钥会保存在连接器配置中。请不要分享该 URL 或相关界面截图。如果密钥泄露，请在 API 密钥页面生成新密钥。

Claude Code（在终端中）：

bash

claude mcp add cpfhub --transport http https://api.cpfhub.io/mcp --header "x-api-key: $CPFHUB_API_KEY"

Cursor（.cursor/mcp.json）：

JSON

{
  "mcpServers": {
    "cpfhub": {
      "url": "https://api.cpfhub.io/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

如需在不消耗积分的情况下测试连接和密钥，可以用 curl 列出工具：

bash

curl -s https://api.cpfhub.io/mcp \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

响应中应列出九个工具：lookup_cpf、lookup_cpf_realtime、lookup_cnpj、bulk_lookup_cpf、bulk_lookup_cnpj、get_bulk_job、create_kyc_link、get_kyc_link 和 get_quota_info。

本地：通过 npx 使用 stdio

仅在 MCP 客户端不支持 HTTP 时使用。服务器运行在您的机器上，但每次查询都会调用 CPFHub.io API，因此需要联网和 API 密钥。

⚠

本地包的限制

@cpfhub/mcp 包中只有 lookup_cpf 可用。get_quota_info 工具在当前版本的包中无法使用（请通过 GET /quota 查看余额），其他工具仅在远程服务器上提供。只要客户端支持 HTTP，请优先使用远程服务器。

Claude Desktop 或 Cursor（通过 npx）：

JSON

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

环境变量（本地）

bash

export CPFHUB_API_KEY=YOUR_API_KEY
npx @cpfhub/mcp

✦

免费获取 API 密钥

在 app.cpfhub.io 创建账户，并在 API 密钥页面生成密钥。免费版每月包含 50 个积分。

可用工具

`lookup_cpf`

标准查询：从 CPFHub.io 数据库返回姓名、性别和出生日期（与 GET /cpf/{cpf} 的数据相同）。每查到 1 个 CPF，按您套餐中一次标准查询的费用计费（默认 1 积分）。未查到的 CPF 不消耗积分。

参数：

字段	类型	必填	说明
`cpf`	`string`	是	带或不带格式符号的 CPF
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥（`x-api-key` 请求头或 `?api_key=`），则可省略

响应（工具的文本内容，JSON 格式）：

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

出错时，工具返回 isError: true，error 为字符串（API 使用葡萄牙语回复，下面这条的意思是“数据库中未找到该 CPF”）：

JSON

{
  "success": false,
  "error": "CPF não encontrado na base de dados"
}

达到每分钟请求限制时，错误中会带有 retry_after（需等待的秒数）。下面这条的意思是“已超出每分钟请求限制，请在 12 秒后重试。”：

JSON

{
  "success": false,
  "error": "Limite de requisições por minuto excedido. Tente novamente em 12 segundos.",
  "retry_after": 12
}

`lookup_cpf_realtime`

实时查询：在调用时向 Receita Federal（巴西联邦税务局）查询，返回姓名、出生日期、死亡年份、登记状态、控制码和查询凭证（与 POST /cpf/realtime 的数据相同）。默认每次成功查询消耗 1.5 积分。您套餐的费用请在控制台中查看。仅限远程服务器。

参数：

字段	类型	必填	说明
`cpf`	`string`	是	带或不带格式符号的 CPF
`birth_date`	`string`	是	持有人的出生日期，格式为 `DD/MM/YYYY` 或 `DDMMYYYY`
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/...",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/..."
  }
}

deathYear 始终出现在响应中，为整数或 null。没有死亡记录或收到的值无效时为 null。有效值必须是 4 位数字，介于 1900 年和当前年份之间，且不早于出生年份。

错误格式与 lookup_cpf 相同（isError: true，error 为字符串），错误信息与 POST /cpf/realtime 一致。出生日期不匹配或 Receita Federal 不可用时，不消耗积分。

`lookup_cnpj`

CNPJ 查询：返回企业法定名称、登记状态、地址、CNAE（经济活动代码）和股东信息（与 GET /cnpj/{cnpj} 的数据相同）。每查到 1 个 CNPJ，按您套餐中一次标准查询计费（默认 1 积分）。无效或未知的 CNPJ 不消耗积分。

参数：

字段	类型	必填	说明
`cnpj`	`string`	是	带或不带格式符号的 CNPJ，支持纯数字或字母数字格式
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "cnpj": "11222333000181",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "nome_fantasia": "EXEMPLO",
    "situacao_cadastral": "Ativa",
    "uf": "SP",
    "municipio": "SAO PAULO",
    "QSA": [
      { "nome_socio": "FULANO DE TAL", "qualificacao_socio": "Sócio-Administrador" }
    ]
  }
}

完整响应的字段与 GET /cnpj/{cnpj} 相同。

`bulk_lookup_cpf`

创建 CPF 批量任务（行为与 POST /cpf/bulk 相同），并立即返回 jobId。每批最多 10,000 个 CPF，无效和重复的条目会被剔除。创建时余额需覆盖所有有效 CPF，但只对查到的 CPF 按标准查询计费。未知、无效和重复的 CPF 不消耗积分。

参数：

字段	类型	必填	说明
`cpfs`	`string[]`	是	CPF 列表，带或不带格式符号
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}

然后使用该 jobId 调用 get_bulk_job 跟踪批量任务进度。

`bulk_lookup_cnpj`

创建 CNPJ 批量任务（行为与 POST /cnpj/bulk 相同）。限制、响应和积分规则与 bulk_lookup_cpf 相同。

参数：

字段	类型	必填	说明
`cnpjs`	`string[]`	是	CNPJ 列表，带或不带格式符号
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

`get_bulk_job`

批量任务的状态和结果（与 GET /cpf/bulk/{jobId} 和 GET /cnpj/bulk/{jobId} 的数据相同）。请重复调用，直到 status 变为 done 或 failed。处于 processing 状态时已可看到部分结果。CNPJ 批量任务的结果列表在 cnpjs 中，格式为 {cnpj, found, data}。不消耗积分。

参数：

字段	类型	必填	说明
`type`	`"cpf" \| "cnpj"`	是	批量任务类型
`job_id`	`string`	是	创建批量任务时返回的 `jobId`
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "cpfs": [
      { "cpf": "12345678909", "found": true, "name": "Fulano de Tal", "nameUpper": "FULANO DE TAL", "gender": "M", "birthDate": "15/06/1990", "day": 15, "month": 6, "year": 1990 },
      { "cpf": "52998224725", "found": false, "name": null, "nameUpper": null, "gender": null, "birthDate": null, "day": null, "month": null, "year": null }
    ]
  }
}

`create_kyc_link`

创建身份验证链接（行为与 POST /kyc/links 相同）。将 url 发送给用户，用户完成带活体检测的自拍并拍摄证件照片。创建链接不消耗积分。每完成一次验证，无论是否通过，都按您套餐中身份验证的价格计费（默认 5 积分）。

参数：

字段	类型	必填	说明
`external_id`	`string`	否	您的客户标识，会在状态查询和 webhook 中返回
`redirect_url`	`string`	否	用户完成后返回的 `https` URL
`expires_in_minutes`	`number`	否	链接有效期，5 到 10,080 分钟（默认 1,440）
`max_attempts`	`number`	否	允许的尝试次数，1 到 10（默认 3）
`language`	`"pt-BR" \| "en" \| "es"`	否	流程语言
`cpf`	`string`	否	预期的 CPF，将与证件进行交叉核对
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": "https://verificar.cpfhub.io/v/...",
    "externalId": "cliente-4821",
    "expiresAt": "2026-10-29T14:00:00.000Z",
    "maxAttempts": 3,
    "language": "pt-BR"
  }
}

`get_kyc_link`

链接的状态和验证结论（与 GET /kyc/links/{id} 的数据相同）。链接的 status：pending、completed、canceled 或 expired。verification.status：approved、rejected 或 manual_review。不返回个人数据，不消耗积分。

参数：

字段	类型	必填	说明
`id`	`string`	是	`create_kyc_link` 返回的 `id`
`api_key`	`string`	否	您的 API 密钥。如果连接时已发送密钥，则可省略

响应：

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": null,
    "externalId": "cliente-4821",
    "status": "completed",
    "attempts": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-10-29T14:00:00.000Z",
    "createdAt": "2026-10-28T14:00:00.000Z",
    "completedAt": "2026-10-28T14:06:12.000Z",
    "verification": {
      "id": "8f3c2a1e-77b0-4d3c-9a1f-0e5b6c7d8e9f",
      "status": "approved",
      "reasons": [],
      "completedAt": "2026-10-28T14:06:12.000Z"
    }
  }
}

`get_quota_info`

返回套餐、剩余和已用积分、计费状态以及账户标识。不消耗积分，余额为零时也可使用。

响应：

JSON

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com"
  }
}

billingStatus 表示套餐资格。账户拥有可使用该套餐的订阅时为 active，包括免费版订阅以及 past_due 等状态。没有有效订阅时为 free，例如 canceled、unpaid 或 incomplete_expired，此时 plan 可能返回 unknown。默认费用为每次标准查询 1 积分，每次实时查询 1.5 积分。您套餐的具体费用和超额用量规则请在控制台中查看。默认限制为标准查询 30 次/分钟（每次提交批量任务计为 1 次），实时查询 5 次/分钟。定制套餐的限制可能不同，请向 CPFHub.io 支持团队确认。超出限制时，API 返回 429 并带有 Retry-After 请求头。

也可以通过 REST 调用：GET /quota，返回内容相同。

工具定义（手动使用）

如果您想在不使用 MCP 服务器的情况下，在系统提示词中使用该工具：

JSON

{
  "name": "lookup_cpf",
  "description": "Retrieve identity data (full name, gender, date of birth) from a Brazilian CPF number using the CPFHub.io API",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "Brazilian CPF number (digits only or formatted as XXX.XXX.XXX-XX)"
      }
    },
    "required": ["cpf"]
  }
}

在 Claude 中的使用示例

配置好 MCP 服务器后，您可以直接问 Claude：

“验证 CPF 123.456.789-09，并告诉我持有人的姓名和出生日期。”

Claude 会自动调用 lookup_cpf，并在回答中包含查询到的数据。

代码仓库

github.com/cpfhub/cpfhub-mcp：本地包的源代码和问题反馈
npm: @cpfhub/mcp：本地包的版本列表

更新于 2026 年 10 月 28 日