Debitura

Debitura MCP 服务

专为跨境债务催收打造的 MCP 服务。 将 Claude、Cursor、VS Code 或任何兼容 MCP 的 Agent 连接到 Debitura，通过 AI 助手管理国际债务追收：查看案件状态、阅读与合作伙伴的对话、获取定价，并提交新的催收案件——由遍布 183 个国家的经审核本地催收合作伙伴按「无回款、不收费」模式处理。

• 端点： https://mcp.debitura.com/mcp（可流式传输的 HTTP）
• 身份验证： 在 XApiKey 请求头中提供你的 Debitura API 密钥（或使用 Authorization: Bearer <key>）
• 获取密钥： 登录 app.debitura.com → API 密钥页面
• 连接器页面： debitura.com/integration/mcp-server

工具

读取

工具	功能说明
ping	测试连接——“✓ 已连接为 {your company}”
list_cases	列出你的催收案件（分页、状态筛选、排序）
get_case	按 ID、你的自有参考编号或 Debitura 案件参考编号获取单个案件
get_case_activity	案件时间线——截至目前发生的事项（返回 { items, currentEngagementPhase }）
get_case_messages	查看与催收合作伙伴的聊天记录
get_case_payments	查看案件追回的款项
get_case_contract_status	查看已签署或阻碍案件处理的合同
get_case_tasks	查看单个案件的待处理任务（行动事项）
list_case_files	列出附加到案件的文件，并提供有时限的下载 URL
get_account_summary	按生命周期阶段统计案件数量——快速了解整体案件组合
list_tasks	查看账户中的所有待处理任务（行动事项），以及 solutionUrl 和解决操作
preview_case	提交前试算定价并检查资格（不会保存任何数据）
list_team_members	查看你的团队——用于标记消息发送者并分配案件负责人

写入

工具	功能说明
create_case	提交催收案件。指示助手先预览并获得用户的明确确认，然后以幂等方式提交（自动设置 Idempotency-Key，可安全重试，不会重复创建案件）
upload_case_file	向案件附加文件（发票副本、合同 — 最大 25 MB）
send_case_message	向案件的催收合作方发送消息，并注明具名团队成员

每个工具都带有 MCP 注释（readOnlyHint / destructiveHint）；写入工具标记为具有破坏性。create_case 是一项法律／财务操作：其工具说明会告知助手在提交前运行 preview_case 并获得用户的明确确认。MCP 客户端是否也会在运行工具前征求确认，取决于客户端及其设置。

分发

Debitura 将此 MCP 服务作为托管服务运行，地址为 https://mcp.debitura.com/mcp。这是唯一受支持的使用方式 — 将任何 MCP 客户端指向该端点，并使用你的 Debitura API 密钥进行身份验证（见下方的安装）。没有已发布的 npm 包：@debitura/mcp-server 包为私有（"private": true），不会发布到 npm 注册表。源码已公开，因此你可以审查它，也可以按需运行自己的副本（见自托管／开发）— 但通常应使用托管端点。

安装

Claude（网页版／桌面版）

设置 → 连接器 → 添加自定义连接器 → URL https://mcp.debitura.com/mcp。

Anthropic 正在逐步推出同一对话框中的请求标头选项，让你无需 OAuth 即可进行身份验证 — 但这是有准入限制的测试版（Anthropic：“请联系我们以提前体验”），因此大多数账户目前还看不到。如果你看到了，请添加标头 x-api-key，并将你的 Debitura API 密钥设为其值。如果没有，请改用 Claude Code 或下方的 Claude Desktop 配置文件方式 — 无论是否能使用测试版，这两种方式现在都可用。

Claude Code

claude mcp add --transport http debitura https://mcp.debitura.com/mcp --header "XApiKey: YOUR_API_KEY"

Claude Desktop（无法使用测试版的请求标头选项）

直接编辑 claude_desktop_config.json，完全绕过连接器 UI — 这是与网页同步的连接器 UI 不同的独立机制，无需 OAuth — 并使用 mcp-remote 桥接工具：

{
  "mcpServers": {
    "debitura": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.debitura.com/mcp", "--header", "XApiKey:${DEBITURA_KEY}"],
      "env": { "DEBITURA_KEY": "YOUR_API_KEY" }
    }
  }
}

文件位置：macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json。保存后重启 Claude Desktop — 此服务会显示在“设置” → “连接器” → “管理连接器”下，即使你从未点过“添加自定义连接器”。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "debitura": {
      "url": "https://mcp.debitura.com/mcp",
      "headers": { "XApiKey": "YOUR_API_KEY" }
    }
  }
}

VS Code（GitHub Copilot）

code --add-mcp '{"name":"debitura","type":"http","url":"https://mcp.debitura.com/mcp","headers":{"XApiKey":"YOUR_API_KEY"}}'

验证

向你的助手询问："Ping Debitura" → 你应该会看到 ✓ Connected as {your company}。

示例提示词

• "我的 Debitura 案件状态如何？有什么需要我处理的吗？"
• "在德国催收一笔 €12,000 的 B2B 债务需要多少费用？"
• "本周催收合作方有新消息吗？"
• "针对柏林的 Acme GmbH 提交一个催收案件，发票编号为 2026-014，金额为 €8,400，2026 年 3 月 1 日到期。"

安全

• 身份验证与租户隔离。 XApiKey 标头即为租户边界。服务是无状态的——每个请求都会创建一个绑定到调用方 API 密钥的新 MCP 服务，并将该密钥直接传递给 Debitura Customer API。不存储任何密钥或案件数据。
• 传输。 托管端点通过 Cloudflare 使用 HTTPS 提供服务。
• 速率限制。 工具调用会转发到 Debitura Customer API，因此你的 API 密钥受 Customer API 的速率限制约束。某些工具每次调用会发起多个 Customer API 请求（例如，get_account_summary 会针对每个生命周期阶段查询一次计数），每个请求都会计入限制。
• **漏洞报告：**请参阅 SECURITY.md。

自托管 / 开发

使用 Debitura MCP 的受支持方式是使用上方的托管端点。以下步骤仅供本地开发 / 审计此代码库使用。

npm install
npm run dev          # starts on :3000, POST /mcp

环境变量	默认值	用途
PORT	3000	监听端口
DEBITURA_API_BASE_URL	https://customer-api.debitura.com	在测试环境中，指向 https://testcustomer-api.debitura.com

请参阅 .env.example 获取环境变量文件模板。

npm run build && npm start        # production-style local run
docker build -t debitura-mcp . && docker run -p 3000:3000 debitura-mcp

部署说明：托管服务会将构建后的应用打包为 zip 并部署到 Azure App Service （参见 .github/workflows/deploy.yml）——生产环境中不会运行 Docker 镜像。Dockerfile 供本地 / 自托管使用。

E2E 测试

使用测试环境运行每个工具（只创建带有 isTest 标记的案件，并删除这些案件）：

DEBITURA_API_BASE_URL=https://testcustomer-api.debitura.com npm run dev   # terminal 1
DEBITURA_TEST_API_KEY=<test key> MCP_URL=http://localhost:3000/mcp npx tsx scripts/e2e.ts

重新生成 API 类型

类型和 HTTP 客户端通过 openapi-typescript 根据 Customer API 的 OpenAPI 规范 （openapi/customer-api.json）生成——其上的精选 16 个工具层由手动编写：

npm run fetch:spec   # pull latest spec + regenerate src/generated/customer-api.d.ts

发布新版本

版本号位于 package.json 中（config.ts 和 client.ts 均从中获取）。更新版本号时，还要更新 server.json——其 version 字段彼此独立，必须与已发布的注册表条目一致。（smithery.yaml 没有版本字段；Smithery 会自动获取软件包版本。）

添加或移除工具时，还要更新上方的工具目录和 scripts/e2e.ts 中的 tools/list 断言（该断言会核对已注册工具的确切集合）。

关于 Debitura

Debitura 是一个覆盖 183 个国家的全球债务催收平台。债权人提交逾期的 B2B 和 B2C 债权；经过审核的当地催收合作伙伴会在债务人所在司法辖区追收债款，通常采用不成功不收费的方式。访问 debitura.com 了解详情 · API 文档见 docs.debitura.com。