Sifende

@sifende/mcp

Sifende 官方 MCP 服务。将 Claude、Cursor 和其他 MCP 客户端连接到你的 Sifende 账户，这样你就可以用自然语言执行如今通过 API 完成的操作：查询 SIFEN 电子单据、下载 KuDE、在名册中查询 RUC，以及在启用相应功能后开具发票、票据和事件。

• 在你的机器上通过 stdio 运行，使用你自己的 API key。没有中间服务，也不会向第三方发送任何内容。
• 默认以只读模式启动。若要开具单据，必须通过变量启用相应功能。
• 使用官方 SDK @sifende/sdk，具备与 API 相同的安全重试、幂等性和总额计算功能。

快速开始

你需要 Node.js 22.18 或更高版本，以及一个 MCP 客户端。无需安装任何内容：客户端会通过 npx 执行服务。

1. 创建 Sandbox API key

在 Sifende 控制面板中，进入 API Keys → 创建 API Key，创建一个 Sandbox API key：它以 sk_sandbox_ 开头（指南）。使用它可以开具单据，而不会向 SIFEN 发送任何内容。

2. 将服务添加到客户端

Claude Code

claude mcp add sifende --env SIFENDE_API_KEY=sk_sandbox_... -- npx -y @sifende/mcp

Claude Desktop。 打开“设置” →“开发者” →“编辑配置”，将此代码块添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "sifende": {
      "command": "npx",
      "args": ["-y", "@sifende/mcp"],
      "env": {
        "SIFENDE_API_KEY": "sk_sandbox_..."
      }
    }
  }
}

Cursor。 同一代码块可放在 ~/.cursor/mcp.json 中；若只用于单个项目，则放在 .cursor/mcp.json 中。其他使用 mcpServers 格式的客户端也适用（Windsurf、Cline、使用其变体的 Zed 等）。

3. 试着查询

你连接的是哪个环境？我的套餐还剩多少份单据？

模型会调用 informacion_servidor 和 consultar_consumo_plan。如果回答“Sandbox”，说明已经正常运行。

4. 开具你的第一张测试发票

若要让模型开具单据，请将 SIFENDE_MCP_ALLOW_WRITE=true 添加到 env 代码块中，然后重启客户端：

"env": {
  "SIFENDE_API_KEY": "sk_sandbox_...",
  "SIFENDE_MCP_ALLOW_WRITE": "true"
}

在 Claude Code 中，使用 --env SIFENDE_MCP_ALLOW_WRITE=true 重新添加服务（先用 claude mcp remove sifende 将其移除）。

然后向它提出请求：

为 Juan Pérez 开具一张现金发票：2 件 T 恤，每件 150.000 Gs，运费 25.000 Gs，增值税 10%，身份证号 1234567。审批通过后，下载 KuDE 给我。

模型会使用 calcular_totales 计算总额，使用 listar_enumeraciones 检查有效值，开具单据，并持续查询状态，直到 SIFEN 批准，然后保存 PDF。开具前，客户端会要求你确认。

环境

API key 的前缀决定所用环境。无需其他 URL 或配置。

前缀	环境	税务效力	事件（取消、作废、指定）
sk_sandbox_	Sifende Sandbox。不会发送到 SIFEN。	否	否。不会显示事件工具。
sk_test_	SIFEN 测试环境。	否	是
sk_live_	生产环境。	是	是

要测试事件，请使用 sk_test_ API key。若要了解服务连接的是哪个环境，请询问模型，或调用 informacion_servidor。

可以请求的内容

查询（始终可用）：

CDC 为 01800123450010010000001... 的单据目前是什么状态？

在名册中查找 RUC 80012345，并告诉我公司名称。

下载单据 01800123450010010000001... 的 KuDE。

SIFEN 接受哪些计量单位代码？

启用写入后：

取消 CDC 为 01800123450010010000001... 的发票，客户拒收了。

将 timbrado 12345678、establishment 001、point 001 下编号 50 到 60 的发票作废。它们因系统错误而被跳过。

为上一张发票中的一件 T 恤退货开具贷项通知单。

使用 sk_live_ 前

使用 sk_live_ API 密钥时，每次开具的都是以你的纳税人名义出具的真实税务单据。

• 监督每项操作。 模型可能会弄错金额、接收方或单据类型。经 SIFEN 批准的单据只能在 48 小时内（发票）或 168 小时内（通知单）通过取消操作撤销。
• 接受写入工具前检查数据。 MCP 客户端会逐个工具请求确认。使用 sk_live_ 时不要关闭确认。
• 只需查询时，请关闭 SIFENDE_MCP_ALLOW_WRITE。 启动时若启用了写入且使用 sk_live_，服务端会向 stderr 写入警告。
• 将 API 密钥视为密码。 它会以明文保存在客户端配置中：不要将其提交到代码仓库。
• 只在自己的机器上运行服务端。 不要通过网络公开它，也不要将其包含在要分发的应用中。

参考

环境变量

变量	默认值	功能
SIFENDE_API_KEY		必填。其前缀决定环境。
SIFENDE_MCP_ALLOW_WRITE	false	设为 true 或 1 后，将显示用于开具单据和记录事件的工具。接受 true、1、false、0 或空值；任何其他值都会阻止服务端启动。
SIFENDE_MCP_KUDE_DIR	系统临时文件夹	descargar_kude 保存 PDF 的文件夹。
SIFENDE_BASE_URL	https://api.sifende.com.py	仅用于指定其他主机。

读取工具

始终可用。

工具	功能
informacion_servidor	环境、版本以及是否已启用写入。不使用网络。
consultar_documento	根据 CDC 查询单据状态（PENDIENTE、APROBADO、APROBADO_OBSERVACION、RECHAZADO、CANCELADO 或 ERROR），并返回 SIFEN 协议和拒绝原因。
descargar_kude	将已批准单据的 KuDE（PDF）保存到本地文件，并返回路径。可选以 base64 格式一并返回。
consultar_contribuyente	查询 API 密钥对应纳税人的 RUC、公司名称、环境和经营活动。
consultar_padron	在 SET 名册中搜索 RUC 或身份证号，并使用接收方字段名称返回数据。
consultar_consumo_plan	查询当前套餐以及包含、已用和可用的单据数量。
listar_enumeraciones	查询 API 各枚举的有效值：付款类型、计量单位、货币、国家/地区等。
consultar_geografia	查询部门、行政区和城市及其 SIFEN 代码。
listar_eventos / consultar_evento	查询已记录的事件（取消、作废、指定接收方）及其在 SIFEN 中的状态。
calcular_totales	使用 SET 官方舍入规则计算单据总额。在本地计算，不调用 API。
obtener_ejemplo_documento	返回包含虚构数据的示例单据：B2C 和 B2B 现金发票、分期付款信用发票、贷项通知单和借项通知单。

写入工具

仅在 SIFENDE_MCP_ALLOW_WRITE=true 时显示。使用 sk_sandbox_ API key 时，仅显示 emitir_documento，因为 Sandbox 不支持事件。

工具	功能	注释
emitir_documento	开具发票、贷项通知单、借项通知单、汇款单或自开发票。返回状态为 PENDIENTE 的 CDC。	readOnlyHint: false，destructiveHint: false
cancelar_documento	取消已批准的文件（发票为 48 h，通知单为 168 h）。	destructiveHint: true
inutilizar_numeracion	作废一段未使用的编号范围。	destructiveHint: true
nominar_documento	指定以匿名方式开具的发票的接收方。	destructiveHint: false

emitir_documento 和 nominar_documento 不会被标记为破坏性操作，因为它们只会添加内容：不会修改或删除已登记的内容。尽管如此，这些操作仍不可撤销（已开具的文件只能在期限内通过取消操作作废）；使用 sk_live_ API key 时，四项工具的描述都会提醒模型，这些操作会登记真实的税务业务，并要求模型与用户确认数据。

资源

URI	内容
sifende://guia/rapida	开具流程、文件规则和事件。
sifende://docs/llms.txt	从 sifende.com.py 下载的文档索引。
sifende://ejemplos/{nombre}	与 obtener_ejemplo_documento 相同的示例文件。

错误

API 错误（Problem Details，RFC 9457）会以易读文本的形式传递给模型：错误代码、详情、每个无效字段、枚举值无效时的可接受值、供支持人员使用的 traceId，以及错误文档链接。

如果在开具文件或登记事件时连接中断，就无法确定操作是否已完成。消息中会包含所用的 idempotencyKey：如果模型使用相同的 idempotencyKey 重复调用，就会收到原始结果，不会重复创建文件。emitir_documento 和事件始终会返回所用的 idempotencyKey。

开发

git clone https://github.com/ithdev/sifende-mcp
cd sifende-mcp
npm ci
npm run lint && npm run typecheck && npm test && npm run build

测试会在内存中启动 MCP 服务，并使用伪造的 fetch 模拟 API，不会发起网络调用。

使用 Inspector 测试

# Listar las herramientas
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs --method tools/list

# Llamar una herramienta
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs \
  --method tools/call --tool-name listar_enumeraciones --tool-arg nombre=tipoPago

# Interfaz web. El Inspector no hereda el entorno: pasá la API key en la interfaz o con -e.
SIFENDE_API_KEY=sk_sandbox_... npm run inspector

发布版本

在 npm 和 MCP Registry 上发布的步骤见 RELEASING.md。

支持

• MCP 服务错误：请提交 issue。
• 漏洞：请按照 SECURITY.md 中的说明私下报告。
• 账户、文件或 API 相关问题：请发送邮件至 [email protected]。

许可证

Apache 2.0。版权所有 2026 ITH E.A.S.；请参阅 NOTICE。