FacturX API

Name: FacturX API
Author: facturxapi.com

本地服务

github.com/facturxapi其他01 天前更新

代码仓库

关于 FacturX API

FacturX API 是供处理电子发票和 Factur-X 的 Agent 使用的 MCP 服务。它通过 FacturX API 提供试运行、转换为 PDF/A-3、验证及查询 EN16931 规则的功能，支持 stdio 和 HTTP 传输。

主要功能

01模拟发票处理
02将发票转换为 Factur-X PDF/A-3
03验证发票文件
04查询 EN16931 规则和字段

适用场景

01转换前检查发票是否就绪
02将发票转换为 PDF/A-3
03查看发票验证错误
04查找规则或代码关联的字段

MCP 相关

该服务将 FacturX API 操作作为 MCP 工具，提供试运行、转换、验证以及错误或规则说明。它支持 stdio 和 Streamable HTTP 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "com-facturxapi": {
      "command": "uvx",
      "args": [
        "facturx-mcp"
      ],
      "env": {
        "FACTURX_API_KEY": "<FACTURX_API_KEY>",
        "FACTURX_BASE_URL": "<FACTURX_BASE_URL>"
      }
    }
  }
}

启动命令uvx facturx-mcp

需要配置的环境变量

FACTURX_API_KEY密钥FacturX API key (free Sandbox key at https://facturxapi.com/api-key)

FACTURX_BASE_URLAPI base URL

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypifacturx-mcp0.1.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

facturx-mcp

FacturX API 官方 MCP 服务：Agent（Claude、Codex、Cursor……）无需编写集成代码，即可模拟、转换为 Factur-X PDF/A-3、验证文件并解释 EN16931 规则。基于 SDK facturx-api 构建；支持 stdio 和 HTTP 传输。

0.1.1 版本，已发布到 PyPI：pip install facturx-mcp。已使用官方 MCP 客户端（Python SDK）测试，尚未与 Claude Code、Codex 或 Cursor 测试（见“已验证内容”）。

安装

pip install facturx-mcp                        # installe aussi facturx-api
export FACTURX_API_KEY=…   # clé Sandbox gratuite : https://facturxapi.com/api-key
# FACTURX_BASE_URL est facultatif à partir de 0.1.2 (production par défaut) ; obligatoire en 0.1.1
facturx-mcp                                   # stdio (défaut)
facturx-mcp --transport streamable-http --port 8765   # HTTP : http://127.0.0.1:8765/mcp

在 MCP 客户端中声明 stdio 服务的典型方式（mcpServers 格式，尚未经过 市面上的客户端测试）：

{"mcpServers": {"facturx": {"command": "facturx-mcp",
  "env": {"FACTURX_API_KEY": "…"}}}}

工具

工具	功能	费用
`facturx_dry_run(invoice, validation_target?, output?)`	模拟；`ready` 读取 `generationReadiness`	免费
`facturx_convert(invoice, out_dir, validation_target?, output?, idempotency_key?)`	写入 `factur-x.pdf` / `.xml`，返回路径、大小、sha256、已验证的目标	1 张发票
`facturx_validate(file_path, validation_target?)`	简要验证报告（前 10 条错误）	按处理的发票计费
`facturx_explain_error(code_or_rule)`	返回与规则（BR-…）、BT 或 JSON 路径相关的公共集成契约字段	免费，无需密钥

工具描述会告诉 Agent 何时调用这些工具、它们会返回什么以及哪些操作会产生费用。API 错误会变成 is_error 结果，文本为 Error executing tool <nom>: {"error": {...}}，其中包含 API 原样发送的 status、code、api_message、 request_id 和 idempotency_key。不会自动重试（api#2111）。目前尚无公开的 API 错误代码注册表（api#2089）： facturx_explain_error 会如实说明这一点，而不会编造解释。

已验证内容（06/11/2026）

6 项离线测试（已安装 facturx-api 和 mcp，运行 PYTHONPATH=src python -m unittest discover -s tests），禁止出站连接。
官方 MCP 客户端（Python SDK mcp 2.3.0，ClientSession）以 stdio 启动 facturx-mcp，连接 staging（release 900685311ea7），使用测试沙盒密钥，时间为 16:02Z。完整跟踪记录位于 traces/stdio-staging-full-path.json：

facturx_explain_error BR-CO-15 -> totals.net (BT-109), totals.tax (BT-110), … depuis GET /api/v1/integration-contract
facturx_dry_run  -> ready=true, generationReadiness ready (request f51f89da-69df-4eea-bf8f-0da1a3e57163)
facturx_convert  -> target verified en16931, xml 4584 o sha256 f332975e…e03c, pdf 20624 o
facturx_validate -> valid=true, validationStatus=valid, profile EN16931, 0 erreur

同一服务通过 streamable HTTP 运行（16:03Z）：tools/list、facturx_explain_error BT-1 和 facturx_dry_run 均正常；使用无效密钥时，facturx_dry_run 会返回带有 invalid_api_key 的 is_error，并保留原始 API 消息（traces/http-staging-*.json）。
跟踪记录和服务日志中均无密钥（已验证）。

尚未验证：通过 Claude Code、Codex 或 Cursor 进行测试（需在创始人的会话中完成）；xml_cii、签名 URL、真实的 409/503 响应；提交至 MCP 目录（需由创始人操作）。

mcp-name: com.facturxapi/mcp

支持 Markdown

登录后评论