CCXT

ccxt-mcp — 官方 CCXT MCP 服务

通过统一的 ccxt API，将 AI Agent（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 及任何 MCP 主机）连接到 100 多家加密货币交易所和预测市场：获取市场数据、账户余额、管理订单，以及在你明确启用后进行交易。

claude mcp add ccxt -- npx -y ccxt-mcp

安全模型（请先阅读）

你的 API 密钥保存在本地，AI 模型永远不会看到它们：

• 服务通过 stdio 在本地运行。没有任何内容托管在远端；密钥绝不会经过任何第三方服务。
• 凭据绝不会作为工具参数：没有任何工具架构接受密钥，因此模型和被提示词注入的页面都无法提供、索取或更改密钥。工具通过名称引用账户（“binance-main”）。
• 密钥只会包含在发往交易所本身的签名 HTTPS 请求中并离开进程——与任何交易机器人相同。
• 每个工具结果、错误和日志行都会经过一个持有已加载密钥值的脱敏过滤器（某些交易所会在错误正文中回显签名 URL——此路径已封堵）。不会输出原始请求 URL、标头或正文。verbose 会被强制禁用。
• 能力等级需主动启用，并由文件控制。 默认情况下，服务只提供公开市场数据。配置账户即可启用私有读取。trading、funds（提现/转账）和 implicitWrites（原始端点）必须在配置文件中分别为每个账户启用——没有任何工具可以编辑配置，因此对话绝不会自行授予权限。未注册的能力等级甚至不会出现在工具列表中。
• 写入操作会先预览并确认（主机支持 elicitation 时使用原生确认表单，否则通过明确的预览与确认令牌往返流程），并根据市场限额和你的名义金额上限进行验证，同时记录到仅追加的审计日志中。

建议启用交易所侧的防护措施（即使你的机器遭到入侵，这些措施仍然有效）：创建时禁用 API 密钥的提现权限，并设置IP 允许列表。

有一点需要坦诚说明：任何拥有文件系统访问权限的本地 Agent 都可以使用自己的工具读取配置文件——这由 MCP 主机的权限模型决定，而非本服务。可用时优先使用主机的密钥存储（见下文），将文件权限设为 chmod 600，并考虑在主机设置中为该路径添加拒绝规则。

安装

需要 Node.js ≥ 18。npm 包为 ccxt-mcp；服务二进制文件为 npx -y ccxt-mcp。

Claude Code

claude mcp add ccxt -- npx -y ccxt-mcp

也可以通过 .mcp.json 按项目配置（可安全提交，不含密钥）：

{ "mcpServers": { "ccxt": { "command": "npx", "args": ["-y", "ccxt-mcp"] } } }

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{ "mcpServers": { "ccxt": { "command": "npx", "args": ["-y", "ccxt-mcp"] } } }

Cursor

~/.cursor/mcp.json（或按项目配置为 .cursor/mcp.json）：

{ "mcpServers": { "ccxt": { "command": "npx", "args": ["-y", "ccxt-mcp"] } } }

VS Code

.vscode/mcp.json — VS Code 的 inputs 机制会将值存储在加密的密钥存储中，这是使用 JSON 配置的主机存储密钥的最佳选项：

{
  "inputs": [
    { "id": "binance-key", "type": "promptString", "password": true, "description": "Binance API key" },
    { "id": "binance-secret", "type": "promptString", "password": true, "description": "Binance API secret" }
  ],
  "servers": {
    "ccxt": {
      "command": "npx", "args": ["-y", "ccxt-mcp"],
      "env": { "BINANCE_APIKEY": "${input:binance-key}", "BINANCE_SECRET": "${input:binance-secret}" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json — mcpServers 结构与 Claude Desktop 相同；支持 ${env:VAR} 插值。

配置

如果没有配置，服务会提供所有交易所的公开市场数据——仅此一项就很实用。

如需添加账户，请创建配置文件（路径可通过 get_safety_status 工具查看）：

• macOS：~/Library/Application Support/ccxt-mcp/config.json
• Linux：~/.config/ccxt-mcp/config.json
• Windows：%APPDATA%\ccxt-mcp\config.json
• 或将 CCXT_MCP_CONFIG 指向任意路径（也支持加载旧版按交易所组织的 keys.local.json 格式）。

{
  "accounts": {
    "binance-testnet": {
      "exchange": "binance",
      "apiKey": "…",
      "secret": "…",
      "sandbox": true,          // testnet — recommended first stop
      "trading": true           // true enables SANDBOX/DEMO trading only
    },
    "binance-main": {
      "exchange": "binance",
      "apiKey": "…",
      "secret": "…",
      "trading": "live",        // live trading requires the explicit string "live"…
      "maxOrderValue": 250,     // …and a per-order USD cap you author (null = opt out)
      "maxDailyValue": 1000,    // optional rolling-24h cap
      "allowedSymbols": ["BTC/USDT", "ETH/*"],  // optional strict allowlist
      "confirm": "live"         // always | live (default) | never
    },
    "polymarket-main": {
      "exchange": "polymarket",
      "walletAddress": "0x…",
      "privateKey": "0x…"
    }
  }
}

账户字段：交易所 requiredCredentials 中的任意凭据（apiKey、secret、password、uid、walletAddress、privateKey 等）、sandbox/demo、defaultType、options（ccxt 构造函数选项）、prediction: true（适用于同时存在于加密货币和预测命名空间中的交易所，例如 hyperliquid），以及下方的安全开关。对文件运行 chmod 600；否则服务会发出警告（或者在设置 "settings": {"strictPermissions": true} 时拒绝运行）。

也可以使用环境变量：<EXCHANGEID>_<CREDENTIAL>（例如 BINANCE_APIKEY、OKX_PASSWORD）可填充缺失的凭据；而 CCXT_MCP_EXCHANGE/CCXT_MCP_APIKEY/CCXT_MCP_SECRET/CCXT_MCP_SANDBOX/CCXT_MCP_TRADING 这组变量会定义一个名为 default 的单一账户。

Claude Desktop（.mcpb bundle）：安装表单用于配置一个交易所。如需使用多个交易所（或启用实盘交易/提现），请将Config file字段设为包含 accounts 映射的 config.json，格式如上所示；也可以直接在默认路径创建该文件，并将表单字段留空。

功能级别

级别	启用项	开关	默认值
market	行情、订单簿、OHLCV、交易、市场、预测事件、只读原始 GET 端点	—	开启
read	余额、订单、自有交易、持仓	存在具有凭据的账户	配置后开启
trading	创建/编辑/取消订单、杠杆、保证金、持仓操作	每个账户设置 "trading": true（sandbox/demo）或 "live"	关闭
funds	提现、内部转账、充值地址	每个账户设置 "funds": true 或 "live"	关闭
implicitWrites	原始 POST/PUT/DELETE 端点（任何交易所专属操作，包括密钥管理）	每个账户设置 "implicitWrites": true	关闭

"trading": true 有意仅适用于 sandbox/demo 账户；实盘交易需要输入 "trading": "live"，并且设置 maxOrderValue（数值，或明确设为 null 以选择不限制）。funds 的 maxTransferValue 也遵循相同规则。是否启用某个级别由你负责——服务负责提供明确的权限门控、确认机制和审计日志（<cache-dir>/ccxt-mcp/journal/）。

工具

market — list_exchanges、describe_exchange、describe_method（搜索/签名/各交易所参数 + 文档链接）、search_markets、get_tickers、get_orderbook、get_ohlcv、get_trades、search_events（预测市场）、call_read_method（任何统一的 fetch*/load* — 在结构上只读）、call_implicit_get（原始 GET 端点）、get_safety_status。

实时（WebSocket） — watch_subscribe 会启动后台 ccxt.pro 数据流；watch_read 会返回最新数据。状态数据流是“当前 X 是什么样”的快照 — watchTicker(s)、watchOrderBook(ForSymbols)、watchOHLCV、watchBalance、watchPositions、watchBidsAsks、watchMarkPrice(s)：服务端会将实时更新合并到完整的当前集合中，因此 watch_read 始终会在 latest 中返回所有已订阅的交易对（多交易对数据流不会只显示刚刚产生变动的交易对）。事件数据流是日志 — watchTrades 以及私有的 watchOrders/watchMyTrades/watch(My)Liquidations（私有数据流需要账户）：watch_read 会按从旧到新的顺序在 events 中返回新项目，并附带游标。将 waitForChange: true 传递给 watch_read，即可阻塞等待下一次更新（或超时），而不是轮询 — 这是等待成交或持仓变更的高效方式。watch_unsubscribe 会停止数据流；watch_list 会显示活跃的数据流。长期运行的服务会保持套接字连接，因此 Agent 始终能获取最新数据；空闲数据流会在 10 分钟后自动停止。

读取 — list_accounts、get_balance、get_orders、get_my_trades、get_positions。

交易 — create_order、edit_order、cancel_order、cancel_all_orders、set_leverage、set_margin_mode、call_write_method（允许列表中的长尾操作：保证金/持仓/批量取消操作）。

资金 — withdraw、transfer、get_deposit_address。隐式写入 — call_implicit_write。

每个列表结果都设有上限并采用分页，以适配主机上下文限制（会在结果中显示截断提示）；默认会剥离原始 info 负载。预测交易所使用相同的工具，并在交易对位置使用（通过 search_events 获取的）结果句柄。

故障排除

• “Trading is not enabled for account …” — 编辑配置文件（见上文的层级）；对话无法更改此设置。
• 沙盒账户出现 AUTH_FAILED — 测试网密钥需从交易所的测试网门户获取，而非使用实盘账户的密钥（反之亦然）。
• HTTP 451 / 地理限制 — 部分交易所会屏蔽云服务/VPN/美国 IP；如有需要，可通过账户 options 设置代理。
• 大型交易所首次调用较慢 — 初次调用 loadMarkets() 可能需要几秒；之后会在磁盘缓存 24 小时。
• npx @modelcontextprotocol/inspector npx -y ccxt-mcp 会打开交互式工具控制台。

开发（在 ccxt monorepo 内）

npm run mcp.ts          # run the server from live TypeScript sources (tsx)
cd mcp && npm test      # unit + schema + integration tests
cd mcp && npm run build # tsc + regenerate js/data/method-docs.json

有关架构、本服务基于的先前工作分析以及决策日志，请参阅 DESIGN.md。