mcp-nfe-io

@codespar/mcp-nfe-io

面向 NFe.io 的 MCP 服务——用于开具 NF-e / NFS-e 财税单据，以及查询巴西的 CNPJ 和 CEP。

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "nfe-io": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nfe-io"],
      "env": {
        "NFEIO_API_KEY": "your-api-key",
        "NFEIO_COMPANY_ID": "your-company-id-or-cnpj"
      }
    }
  }
}

Claude Code

claude mcp add nfe-io -- npx @codespar/mcp-nfe-io

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "nfe-io": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nfe-io"],
      "env": {
        "NFEIO_API_KEY": "your-api-key",
        "NFEIO_COMPANY_ID": "your-company-id-or-cnpj"
      }
    }
  }
}

工具（22）

工具	用途
create_nfse	开具 NFS-e（服务发票）。
get_nfse	按 ID 获取单张 NFS-e。
cancel_nfse	取消 NFS-e。
list_nfse	分页列出 NFS-e，并可按 flowStatus 筛选。
email_nfse	将已开具的 NFS-e PDF 发送给收件人。
create_nfe	开具 NF-e（商品发票）。
get_nfe	按 ID 获取单张 NF-e。
cancel_nfe	取消 NF-e。
list_nfe	分页列出 NF-e，并可按状态筛选。
get_nfe_pdf	返回已开具 NF-e 的 DANFE PDF URL。
consult_cnpj	按 CNPJ 查询巴西公司信息（法定名称、状态、地址）。
consult_cep	将巴西邮政编码（CEP）解析为完整地址。
correct_nfe	为已获授权的 NF-e 开具 Carta de Correção（CC-e）。
get_nfe_xml	返回 NF-e 的已授权 XML URL。
get_nfse_pdf	返回已开具 NFS-e 的 PDF URL。
get_nfse_xml	返回已开具 NFS-e 的 XML URL。
list_companies	列出 NFe.io 账户中注册的公司。
get_company	按 ID 或 CNPJ 获取单家公司。
create_company	在 NFe.io 上注册新公司。
list_webhooks	列出为公司注册的 webhook 端点（发票事件回调）。
create_webhook	注册 webhook 端点。
delete_webhook	按 ID 移除 webhook 端点。

环境变量

变量	必需	备注
NFEIO_API_KEY	是	开具 + 查询权限。NFe.io 支持将其拆分为两个密钥；任一密钥均可使用。
NFEIO_COMPANY_ID	否	默认公司 ID（或 CNPJ）。每次调用的 company_id 参数会覆盖此值。

主机

NFe.io 将 API 分布在三个主机名下。本服务会自动将工具映射到正确的主机：

• api.nfse.io — 商品发票
• api.nfe.io — 服务发票 + 公司管理
• nfe.api.nfe.io — 查询（CNPJ、CEP）

演示模式

传入 --demo 或设置 MCP_DEMO=true，即可返回预设响应，而不访问网络。适用于文档、屏幕录制和 CI。

链接

• NFe.io REST API 文档
• CodeSpar MCP Brazil 目录

企业版

需要为 Agent 付款提供治理、预算限制和审计追踪？CodeSpar Enterprise 在这些 MCP 服务之上增加了策略引擎、付款路由和合规模板。

身份验证

启动服务前设置以下环境变量：

• NFEIO_API_KEY （必需，密钥） — NFe.io API 密钥（开具 + 查询）
• NFEIO_COMPANY_ID — 未在单次调用中提供时使用的默认公司 ID（CNPJ 或 NFe.io 公司 UUID）

请在提供商的开发者门户中获取凭据：https://nfe.io/docs。

许可证

MIT