CoinVello

@coinvello/mcp

适用于 CoinVello API 的 Model Context Protocol 服务。CoinVello 是非托管型加密货币支付处理服务商（无需 KYC，商户保管密钥，费用以预付额度结算，支持 11 个网络）。

让 Claude、Cursor、Windsurf、ChatGPT 或任何 MCP 客户端能够创建结账会话、查看发票和付款、注册 Webhook、验证 Webhook 签名、管理额度并模拟测试付款，助力编写集成代码。

npx -y @coinvello/mcp            # stdio (what every desktop client uses)
npx -y @coinvello/mcp --http 3333  # Streamable HTTP on http://127.0.0.1:3333/mcp

# from a checkout of this repo instead
npm install && npm run build && node dist/index.js

托管版（无需安装）

https://mcp.coinvello.com/mcp 会通过 Streamable HTTP 为你运行此服务。每次请求都需发送你自己的密钥，格式为 Authorization: Bearer cv_test_...（也可以使用 X-CoinVello-Api-Key，或在仅支持查询参数的客户端中设置 api_key）。托管服务不存储任何内容，只接受测试密钥，也绝不会记录密钥。你也可以通过 npx -y @coinvello/mcp --http --hosted 自行运行。

{ "mcpServers": { "coinvello": { "url": "https://mcp.coinvello.com/mcp", "headers": { "Authorization": "Bearer cv_test_..." } } } }

文档

AI 助手网站和设置指南	https://coinvello.com/ai
完整集成指南（单文件，面向大模型编写）	https://coinvello.com/llms-full.txt
开发者文档和 SDK	https://coinvello.com/developers
OpenAPI 3.1 参考	https://coinvello.com/.well-known/openapi.yaml
MCP 注册表	io.github.CoinVello/coinvello
源码	https://github.com/CoinVello/coinvello-ai (api/ai/mcp-server)
支持	[email protected]

配置

变量	必需	含义
COINVELLO_API_KEY	是	来自 https://coinvello.com/app/settings.php（Settings -> API keys）的 cv_test_...。任何 cv_test_ 字符串都可用于本地模拟服务。
COINVELLO_API_BASE	否	默认值为 https://api.coinvello.com/v1。参考模拟服务使用 http://localhost:4242/v1。
COINVELLO_ALLOW_LIVE	否	除非该值为 1，否则服务不会使用 cv_live_ 密钥启动。Agent 应使用测试模式进行开发。
COINVELLO_API_VERSION	否	固定 CoinVello-Version（默认：账户版本，目前为 2026-10-01）。

客户端设置

Claude Desktop

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

Claude Code

claude mcp add coinvello -e COINVELLO_API_KEY=cv_test_... -- npx -y @coinvello/mcp

或将配置放在项目根目录的 .mcp.json 中（与团队共享，密钥通过环境变量提供）：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "${COINVELLO_API_KEY}" }
    }
  }
}

Cursor

项目级 .cursor/mcp.json 或全局 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "coinvello": {
      "command": "npx",
      "args": ["-y", "@coinvello/mcp"],
      "env": { "COINVELLO_API_KEY": "cv_test_..." }
    }
  }
}

VS Code（Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "coinvello": { "type": "stdio", "command": "npx", "args": ["-y", "@coinvello/mcp"], "env": { "COINVELLO_API_KEY": "cv_test_..." } }
  }
}

远程 / HTTP 客户端（ChatGPT 连接器、托管 Agent）

在你自己的 HTTPS 反向代理后运行 coinvello-mcp --http 3333，并将客户端指向 https://your-host/mcp。HTTP 模式为无状态模式（每个请求启动一个服务实例），默认绑定到 127.0.0.1（可通过 MCP_HTTP_HOST=0.0.0.0 修改）。它会使用环境变量中的密钥， 因此请将其置于身份验证保护之下：该模式面向你自己的 Agent，而非公众。

工具

工具	功能
create_checkout_session	POST /checkout-sessions：托管式支付页面；返回用于重定向的 url 和 invoice_id
get_invoice	GET /invoices/{id}（或 GET /checkout-sessions/{cs_id}?expand=invoice）
list_invoices	GET /invoices，支持按状态、order_id 和 email 筛选
list_payments	GET /payments，支持按 invoice_id、状态、chain 和 tx_hash 筛选
create_wallet	POST /wallets（BTC 使用 xpub，EVM/Solana/Tron 使用地址）。会在本地拒绝 xprv。
list_wallets	GET /wallets
create_webhook	POST /webhooks；whsec_ 密钥仅返回一次
verify_webhook_signature	针对原始请求体，在本地验证 CoinVello-Signature 标头的 HMAC（不会调用 API）
get_credits_balance	GET /credits/balance
list_credit_bundles	GET /credits/bundles
create_credit_purchase	POST /credits/purchases；返回支付选项和 checkout_url
get_rates	GET /rates
list_assets	GET /assets（可选的 chain 筛选条件）
simulate_test_payment	POST /test/simulate_payment（仅限测试密钥）
list_records	GET /records：记录账簿（支付、费用、积分购买），按发生时的价值计价；支持按 type、asset、chain、invoice、order、tx、日期和货币筛选
get_records_summary	GET /records/summary：查询某一时段的销售额、收到的市值、退款、费用和净收款，可选择分组
create_export	POST /exports：将记录或任意数据集导出为 CSV、Excel 或 JSON 文件（QuickBooks、Xero、Koinly、CoinTracker、CoinLedger 预设）；返回包含 download_url 的导出结果
get_export	GET /exports/{id}：轮询状态直至变为 ready，读取 file.sha256 和 download_url

每个工具都会返回原始 API JSON（也会作为 structuredContent 返回）。API 错误会作为工具错误返回，其中包含 http_status、CoinVello 的 error 信封（type、code、message、request_id）和 hint。

资源

URI	内容
coinvello://docs/llms-full.txt	完整的单文件集成指南（身份验证、结账、重定向、Webhook 验证、轮询、积分、错误，以及 curl/Node/Python/PHP 示例）
coinvello://docs/llms.txt	简短的 llms.txt 索引
coinvello://openapi.yaml	OpenAPI 3.1 规范

文档会在构建时打包；如果缺失，则会从 coinvello.com 获取。

提示词

integrate-coinvello-into-<framework>，适用于 nextjs、express、fastapi、flask、django、 laravel、rails、sinatra、go、woocommerce、shopify、generic，此外还有 integrate-coinvello-into-framework，可接受自由格式的 framework 参数。可选参数： currency、assets。每条提示词都会要求 Agent 阅读指南资源、添加结账路由、添加带签名验证和 event.id 去重功能的原始请求体 Webhook 路由，并通过 simulate_test_payment 端到端验证。

典型的 Agent 会话

1. list_assets -> 选择商家可以接受的资产。
2. 使用应用的 /webhooks/coinvello URL 调用 create_webhook -> 将密钥存储在环境文件中。
3. 编写代码（参见 integrate-coinvello-into-* 提示词或 api/ai/cookbook）。
4. 调用 create_checkout_session -> 针对 invoice_id 调用 simulate_test_payment，并设置足够的确认数。
5. get_invoice 显示 paid；应用的 Webhook 处理程序已收到带有真实签名的事件。
6. 使用 verify_webhook_signature 调试拒绝投递的处理程序。
7. 记账：调用 list_records（测试模式下使用 include_simulated: true）-> 针对某一时段调用 get_records_summary -> 调用 create_export（format: "xlsx"）-> 调用 get_export 直至状态变为 ready -> 下载 download_url 并检查 file.sha256。

开发

npm install
npm run build          # copies docs into dist/docs and compiles TypeScript
npm test               # smoke test against the mock: needs api/reference-server running on :4242
npm run dev            # tsx src/index.ts (stdio)

冒烟测试：运行 cd api/reference-server && npm install && npm start，然后在此处运行 COINVELLO_API_BASE=http://localhost:4242/v1 npm test。此测试会运行全部 18 个工具、三个 资源和提示词，验证由模拟服务的 webhook 接收端捕获的真实签名投递，并检查 xprv 防护。模拟服务未实现钱包的增删改查，因此 create_wallet / list_wallets 在此处预期会返回干净的 404 工具错误。

安全说明

• 在 Agent 编写代码时，请让服务使用测试密钥。COINVELLO_ALLOW_LIVE=1 是明确选择启用的选项。
• 服务绝不会记录 API 密钥或 webhook 密钥。工具输出确实会包含 create_webhook 返回的 secret，因为 API 只有在此时才会返回它。
• create_wallet 会在任何看起来像扩展私钥的内容离开本机之前拒绝它。
• 此处的任何操作都不会转移资金：CoinVello 是非托管式的，且该 API 没有“发送”操作。

许可证：MIT。源码：https://github.com/CoinVello/coinvello-ai（镜像）。问题反馈：https://github.com/CoinVello/coinvello-ai/issues 或 [email protected]