mcp-asaas

@codespar/mcp-asaas

Asaas 的 MCP 服务——支持 Pix、boleto 和信用卡支付的账单自动化

快速开始

Claude Desktop

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

{
  "mcpServers": {
    "asaas": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-asaas"],
      "env": {
        "ASAAS_API_KEY": "your-key",
        "ASAAS_SANDBOX": "true"
      }
    }
  }
}

Claude Code

claude mcp add asaas -- npx @codespar/mcp-asaas

Cursor / VS Code

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

{
  "servers": {
    "asaas": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-asaas"],
      "env": {
        "ASAAS_API_KEY": "your-key",
        "ASAAS_SANDBOX": "true"
      }
    }
  }
}

工具（24 个）

工具	用途
create_payment	在 Asaas 创建付款（Pix、boleto 或信用卡）；将 installments（>=2）与 billingType: CREDIT_CARD 一起传入，可分期为等额月付款
get_payment	按 ID 获取付款详情
list_payments	列出付款，可选筛选条件
get_pix_qrcode	获取付款的 Pix 二维码（返回有效载荷和图像）
get_boleto	获取付款的 boleto 数字支付行和条形码
create_customer	在 Asaas 创建客户
list_customers	列出客户，可选筛选条件
create_subscription	创建定期订阅
get_balance	获取当前账户余额
list_subscriptions	列出订阅，可选筛选条件
cancel_subscription	按 ID 取消订阅
get_webhook_events	列出 Webhook 事件（付款确认、转账等）
create_subaccount	创建用于付款分账的子账户
get_installments	通过 id 获取现有付款的分期详情；或不传入 id，改为传入 value + installments，预览假设的分期计划
create_transfer	创建银行转账（Pix 转出或 TED）
create_pix_qrcode	生成用于收款的静态 PIX 二维码
list_transfers	列出转账，可选筛选条件
create_notification	创建 Webhook 通知配置
list_notifications	列出 Webhook 通知配置
get_customer	按 ID 获取客户详情
update_payment	更新待处理的付款
delete_payment	按 ID 删除付款
refund_payment	退还已收取的付款
get_subscription	按 ID 获取订阅详情

身份验证

Asaas 使用通过 access_token 标头传递的 API 密钥。你可以在 Asaas 控制面板中生成密钥。

沙盒 / 测试

Asaas 提供完整的沙盒环境，地址为 sandbox.asaas.com。设置 ASAAS_SANDBOX=true 即可使用。

获取凭据

1. 访问 Asaas
2. 创建账户，或前往 sandbox.asaas.com 注册沙盒账户
3. 前往 Integracoes > API 并生成 API 密钥
4. 设置 ASAAS_API_KEY 环境变量

环境变量

变量	必填	描述
ASAAS_API_KEY	是（演示模式除外）	Asaas 控制面板中的 API 密钥
ASAAS_SANDBOX	否	设置为 "true" 以启用沙盒模式
MCP_DEMO	否	设置为 "true"（相当于在命令行中传入 --demo），以使用有状态的演示模式样例数据——无需 API 密钥

演示模式

传入 --demo 标志（或设置 MCP_DEMO=true），即可让每个工具返回确定性的模拟响应，而不调用真实的 Asaas API。适用于构建和测试 Agent，无需消耗沙盒凭据。

create_payment 和 get_installments 的演示处理程序具有状态：create_payment 每次调用都会生成不同的 ID （pay_demo_001、pay_demo_002……），并且在使用 billingType: CREDIT_CARD + installments >= 2 + value > 0 调用时， 会将分期计划记录到进程内账本中。随后针对该 ID 调用 get_installments({ id }) 时，会返回记录的分期计划。get_installments 还支持预览路径——不传入 id，而是传入 value + installments，即可返回假设的分期计划（status: "PREVIEW"、preview: true），但不会创建付款。其他工具会返回静态模拟数据。

# Start the server in demo mode (no key required):
npx -y @codespar/mcp-asaas --demo

路线图

v0.2（计划中）

• list_subscriptions — 列出所有定期订阅，并支持筛选
• cancel_subscription — 取消有效订阅
• get_webhook_events — 列出 Webhook 事件，以便调试集成
• create_subaccount — 创建用于市场分账的子账户
• get_installments — 获取付款的分期详情

v0.3（计划中）

• create_anticipation — 申请应收款提前结算
• get_fiscal_info — 获取付款的财税信息
• batch_payments — 在单个请求中创建多笔付款

想要参与贡献？提交 PR 或申请添加工具。

链接

• Asaas 网站
• Asaas API 文档
• MCP Dev LATAM
• 落地页

企业版

需要为 Agent 付款设置治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务的基础上提供策略引擎、付款路由和合规模板。

许可证

MIT