mcp ezpay电子语音

台湾ezPay电子发票API MCP服务器

](https://pypi.org/project/mcp-ezpay-einvoice/) ![Python](https://pypi.org/project/mcp-ezpay-einvoice/) ![License: MIT](https://opensource.org/licenses/MIT) ![MCP](https://modelcontextprotocol.io/) ](https://github.com/asgard-ai-platform/mcp-ezpay-einvoice/stargazers) ](https://github.com/asgard-ai-platform/mcp-ezpay-einvoice/issues) ](https://github.com/asgard-ai-platform/mcp-ezpay-einvoice/commits/main)

Traditional Chinese（繁体中文）

______________________________________________________________________

概述

一个MCP（模型上下文协议）服务器，通过 ezPay 平台。涵盖发票开具（B2B/B2C）、触发、作废、津贴（信用票据/退款）和查询——所有这些都可以通过标准MCP协议由Claude等人工智能助理访问。

部分 Asgard人工智能平台开源生态系统。

特性

发票 --开具B2B（企业）或B2C（个人）电子发票，其中包含完整的商品详细信息、税务类型、承运商和捐赠代码
trigger_invoice --触发延期或预定发票以立即开具
void_invoice --在允许的报告期内作废已开具的发票
发放津贴 --根据现有发票发放津贴（贷记单/部分退款）
触发_允许 --确认或取消待定的津贴
无效_允许 --已确认的津贴无效
查询_语音 --按发票号或订单号查询发票明细
AES-256-CBC加密 --实现ezPay加密形式的POST协议（URL编码、PKCS7填充、AES加密、十六进制编码）
CheckCode验证 --基于SHA-256的响应验证
双重环境 --支持两种测试(cinv.ezpay.com.tw)和生产(inv.ezpay.com.tw)环境

先决条件

Python 3.10或更高版本
具有API凭证（MerchantID、HashKey、HashIV）的ezPay商户账户

- 测试环境：注册https://cinv.ezpay.com.tw/ - 生产环境：注册地址：https://inv.ezpay.com.tw/

安装

选项1：从PyPI安装

pip install mcp-ezpay-einvoice

或与紫外线:

uv pip install mcp-ezpay-einvoice

选项2：直接使用uvx运行（无需安装）

EZPAY_MERCHANT_ID=your_id EZPAY_HASH_KEY=your_key EZPAY_HASH_IV=your_iv \
  uvx mcp-ezpay-einvoice

选项3：从源代码安装

git clone https://github.com/asgard-ai-platform/mcp-ezpay-einvoice.git
cd mcp-ezpay-einvoice
uv venv && source .venv/bin/activate
uv pip install -e .

配置

在运行服务器之前设置以下环境变量：

环境变量	必填	说明
`EZPAY_MERCHANT_ID`	是	您的ezPay商家ID
`EZPAY_HASH_KEY`	是	AES-256加密密钥（32个字符）
`EZPAY_HASH_IV`	是	AES-CBC初始化向量（16个字符）
`EZPAY_IS_PRODUCTION`	否	设置为 `true` 用于生产。默认为 `false` （测试环境）

您还可以复制 .env.example 文件到 .env 并填写您的值：

cp .env.example .env

用法

克劳德桌面版

将以下内容添加到您的 claude_desktop_config.json:

使用uvx（推荐使用，无需手动安装）：

{
  "mcpServers": {
    "ezpay-einvoice": {
      "command": "uvx",
      "args": ["mcp-ezpay-einvoice"],
      "env": {
        "EZPAY_MERCHANT_ID": "your_merchant_id",
        "EZPAY_HASH_KEY": "your_hash_key",
        "EZPAY_HASH_IV": "your_hash_iv",
        "EZPAY_IS_PRODUCTION": "false"
      }
    }
  }
}

使用pip安装：

{
  "mcpServers": {
    "ezpay-einvoice": {
      "command": "mcp-ezpay-einvoice",
      "env": {
        "EZPAY_MERCHANT_ID": "your_merchant_id",
        "EZPAY_HASH_KEY": "your_hash_key",
        "EZPAY_HASH_IV": "your_hash_iv",
        "EZPAY_IS_PRODUCTION": "false"
      }
    }
  }
}

克劳德代码

如果你克隆了仓库 .mcp.json 项目中的根由Claude Code自动发现。只需设置环境变量：

export EZPAY_MERCHANT_ID=your_merchant_id
export EZPAY_HASH_KEY=your_hash_key
export EZPAY_HASH_IV=your_hash_iv

或者通过CLI添加服务器：

claude mcp add ezpay-einvoice -- uvx mcp-ezpay-einvoice

光标/风帆

添加到MCP设置(.cursor/mcp.json 或同等）：

{
  "mcpServers": {
    "ezpay-einvoice": {
      "command": "uvx",
      "args": ["mcp-ezpay-einvoice"],
      "env": {
        "EZPAY_MERCHANT_ID": "your_merchant_id",
        "EZPAY_HASH_KEY": "your_hash_key",
        "EZPAY_HASH_IV": "your_hash_iv",
        "EZPAY_IS_PRODUCTION": "false"
      }
    }
  }
}

直接运行

# With environment variables
EZPAY_MERCHANT_ID=your_id EZPAY_HASH_KEY=your_key EZPAY_HASH_IV=your_iv \
  python mcp_server.py

# Or with uvx
EZPAY_MERCHANT_ID=your_id EZPAY_HASH_KEY=your_key EZPAY_HASH_IV=your_iv \
  uvx mcp-ezpay-einvoice

测试

# Validate credentials and connectivity
python scripts/auth/test_connection.py

# Run all 7 tool E2E tests
python tests/test_all_tools.py

使用示例

一旦MCP服务器运行，AI助手（例如Claude）可以代表您调用这些工具。以下是真实世界的场景，显示了你说的话以及人工智能的反应。

______________________________________________________________________

“帮助我为购买测试产品的客户开具发票”

你：帮我开一张发票，客人买了一个测试商品105元含税，要印纸本发票

AI呼叫：

issue_invoice(
  merchant_order_no = "ORDER20260404001",
  buyer_name        = "Test Buyer",
  category          = "B2C",
  tax_type          = "1",
  tax_rate          = 5,
  amt               = 100,
  tax_amt           = 5,
  total_amt         = 105,
  item_name         = "Test Product",
  item_count        = "1",
  item_unit         = "pc",
  item_price        = "105",
  item_amt          = "105",
  print_flag        = "Y",
  status            = "1",
)

结果： SUCCESS --发票 TE00000000 已发行，金额NT$105，随机码 9393响应包括用于打印的条形码、QRcodeL和QRcodeR。

______________________________________________________________________

“开具带有买方税务ID的B2B发票”

你：帮我开一张B2B发票给统编54352706的公司，品名是顾问服务费10000元加税500元

AI呼叫：

issue_invoice(
  merchant_order_no = "B2B20260404001",
  buyer_name        = "範例科技股份有限公司",
  buyer_ubn         = "54352706",
  category          = "B2B",
  tax_type          = "1",
  tax_rate          = 5,
  amt               = 10000,
  tax_amt           = 500,
  total_amt         = 10500,
  item_name         = "顧問服務費",
  item_count        = "1",
  item_unit         = "式",
  item_price        = "10000",
  item_amt          = "10000",
  print_flag        = "Y",
  status            = "1",
)

结果： SUCCESS --与买方UBN开具的B2B发票 54352706。打印的发票包括用于税务申报的条形码和二维码。

______________________________________________________________________

“使用手机条形码载体开具B2C发票”

你：客人要存手机条形码载具/ABC1234，不印纸本，品项是拿铁咖啡2杯65元、巧克力蛋糕1个85元

AI呼叫：

issue_invoice(
  merchant_order_no = "POS20260404001",
  buyer_name        = "顧客",
  category          = "B2C",
  carrier_type      = "0",
  carrier_num       = "/ABC1234",
  tax_type          = "1",
  tax_rate          = 5,
  amt               = 205,
  tax_amt           = 10,
  total_amt         = 215,
  item_name         = "拿鐵咖啡|巧克力蛋糕",
  item_count        = "2|1",
  item_unit         = "杯|個",
  item_price        = "65|85",
  item_amt          = "130|85",
  print_flag        = "N",
  status            = "1",
)

结果： SUCCESS --发票存储到电话条形码载体 /ABC1234，不打印纸质副本。

______________________________________________________________________

“查询我刚刚开具的发票”

你：帮我查一下订单ORDER20260404001的发票数据

AI呼叫：

query_invoice(
  search_type       = "1",
  merchant_order_no = "ORDER20260404001",
  total_amt         = 105,
)

结果： SUCCESS --返回完整的发票详细信息，包括发票号码 TE00000000、买家信息、税务明细（金额：100，税额：5，总金额：105）、项目详细信息、发票状态（1=已开具）、上传状态、条形码和二维码。

______________________________________________________________________

“我需要为退回的商品退款”

你：客人退了一杯拿铁65元，帮我对发票TE00000000开折让

AI呼叫：

issue_allowance(
  invoice_no        = "TE00000000",
  merchant_order_no = "ORDER20260404001",
  item_name         = "拿鐵咖啡",
  item_count        = "1",
  item_unit         = "杯",
  item_price        = "65",
  item_amt          = "65",
  item_tax_amt      = "3",
  total_amt         = 68,
  status            = "1",
)

结果： SUCCESS --根据发票开具的津贴 TE00000000 新台币68元（65+3税）。剩余发票金额将相应更新。

______________________________________________________________________

“作废那张发票——它是错开的”

你：发票TE00000000开错了，帮我作废，原因是误开发票

AI呼叫：

void_invoice(
  invoice_number = "TE00000000",
  invalid_reason = "誤開發票",
)

结果： SUCCESS --发票 TE00000000 无效。平台将通知买方并将无效记录上传至税务机关。

注：发票只能在下一个奇数月的14日之前作废（例如，3月至4月开具的发票可以在5月14日之前废止）。

______________________________________________________________________

“为下周创建计划发票”

你：帮我建一张预约发票，预计2026-04-10开立，金额1000元含税

AI呼叫：

issue_invoice(
  merchant_order_no  = "SCH20260404001",
  buyer_name         = "預約客戶",
  category           = "B2C",
  tax_type           = "1",
  tax_rate           = 5,
  amt                = 952,
  tax_amt            = 48,
  total_amt          = 1000,
  item_name          = "訂閱服務",
  item_count         = "1",
  item_unit          = "式",
  item_price         = "1000",
  item_amt           = "1000",
  print_flag         = "Y",
  status             = "3",
  create_status_time = "2026-04-10",
)

结果： SUCCESS --发票数据已保存，计划于2026年4月10日开具。如果您需要提前发布，请使用 trigger_invoice 立即触发它。

______________________________________________________________________

“立即触发该计划发票”

你：预约发票SCH20260404001要提前开立，帮我触发

AI呼叫：

trigger_invoice(
  invoice_trans_no  = "26040423034604894",
  merchant_order_no = "SCH20260404001",
  total_amt         = 1000,
)

结果： SUCCESS --计划发票立即触发并发出。返回发票号码和随机代码。

工具参考

工具	说明	关键参数
`issue_invoice`	开具B2B/B2C电子发票	`category`, `buyer_name`, `tax_type`, `amt`, `total_amt`, `item_name`, `item_count`, `item_price`, `print_flag`
`trigger_invoice`	触发延期/计划发票	`invoice_trans_no`, `merchant_order_no`, `total_amt`
`void_invoice`	作废已开具的发票	`invoice_number`, `invalid_reason`
`issue_allowance`	发行备抵（贷记单）	`invoice_no`, `item_name`, `item_count`, `item_price`, `total_amt`
`trigger_allowance`	确认或取消待定津贴	`allowance_no`, `allowance_status` (`C`=确认， `D`=取消）
`void_allowance`	已确认的津贴无效	`allowance_no`, `invalid_reason`
`query_invoice`	查询发票明细	`search_type` (`0`=按发票号码， `1`=按订单号）

错误代码参考

常见ezPay API响应状态代码：

状态	含义
`SUCCESS`	操作已成功完成
`LIB10001`	商户ID不存在
`LIB10002`	加密验证失败
`LIB10003`	时间戳已过期
`INV10001`	重复的商户订单号
`INV10003`	发票号码不存在
`INV20001`	发票已作废
`INV20002`	发票作废期已过
`ALW10001`	备抵金额超过发票金额
`ALW10002`	津贴编号不存在

有关完整的错误代码列表，请参阅 ezPay API文档.

建筑

stdio (JSON-RPC 2.0)
  -> mcp_server.py           Entry point, side-effect import triggers tool registration
    -> app.py                FastMCP("mcp-ezpay-einvoice") singleton
      -> tools/invoice_tools.py    7 @mcp.tool() decorated functions
        -> connectors/ezpay_client.py   Encrypted form POST connector
          -> auth/ezpay_crypto.py       AES-256-CBC encrypt + CheckCode verify
            -> config/settings.py       Endpoints, URL builder, env var config

mcp-ezpay-einvoice/
|-- app.py                          # FastMCP server singleton
|-- mcp_server.py                   # Entry point (stdio transport)
|-- config/settings.py              # API endpoints, URL builder, credentials
|-- connectors/ezpay_client.py      # Encrypted form POST connector
|-- auth/ezpay_crypto.py            # AES-256-CBC encryption, CheckCode
|-- tools/invoice_tools.py          # 7 MCP tools (invoice + allowance lifecycle)
|-- tests/test_all_tools.py         # E2E test runner
|-- scripts/auth/test_connection.py # Connection and credential validator
|-- .mcp.json                       # Claude Code auto-discovery config
`-- .env.example                    # Environment variable template

贡献

看贡献.md 有关设置说明和指南。

分叉存储库
创建要素分支： git checkout -b feat/your-feature
进行更改并运行测试
提交拉取请求

许可证

MIT许可证——见许可证了解详情。

Asgard生态系统的一部分

该服务器是Asgard AI平台的一部分，将AI助手连接到电子商务、金融、政府数据等领域的现实服务。查看完整 Asgard人工智能平台.

MCP Ezpay Einvoice

快速接入

详细介绍

mcp ezpay电子语音

概述

特性

先决条件

安装

选项1：从PyPI安装

选项2：直接使用uvx运行（无需安装）

选项3：从源代码安装

配置

用法

克劳德桌面版

克劳德代码

光标/风帆

直接运行

测试

使用示例

“帮助我为购买测试产品的客户开具发票”

“开具带有买方税务ID的B2B发票”

“使用手机条形码载体开具B2C发票”

“查询我刚刚开具的发票”

“我需要为退回的商品退款”

“作废那张发票——它是错开的”

“为下周创建计划发票”

“立即触发该计划发票”

工具参考

错误代码参考

建筑

贡献

许可证

Asgard生态系统的一部分

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP