mcp ezpay电子语音
台湾ezPay电子发票API MCP服务器
______________________________________________________________________
概述
一个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 configmcp-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人工智能平台.