Capital.com MCP Server

Capital.com MCP 服务

面向 Capital.com Open API 的可自托管 Model Context Protocol（MCP） 服务，使用 Python 和 FastMCP 编写。它向任何 MCP 客户端提供 42 个安全且受保护的交易和市场数据工具——采用两阶段执行、允许列表和演示账户优先策略；支持 stdio 或 HTTP。基于经过测试的 capitalcom-cli 经纪商引擎（SDK）构建。

兼容： Claude Desktop · Claude Code · Cursor · VS Code（Copilot）· Windsurf · ChatGPT——以及任何 MCP 客户端。

⚠️ 非官方，仅供教育用途。 与 Capital.com 无关联。交易有风险，本内容不构成财务建议。交易默认禁用；所有交易均采用两阶段流程（预览 → 确认 → 执行），并设有允许列表和规模／频率限制。请从演示账户开始。采用 Apache-2.0 许可。

安装

无需克隆——uvx 会在隔离的临时环境中运行，并始终获取最新的测试版：

uvx capitalcom-mcp --help        # smoke test

或者使用 pipx 安装持久命令：

pipx install capitalcom-mcp

生产环境／真实资金使用时锁定版本

uvx capitalcom-mcp 始终运行最新发布版本。尝试使用时这样做没问题，但在生产环境或使用真实资金时，请锁定确切版本，避免意外更新改变工具行为：

{
  "mcpServers": {
    "capitalcom": {
      "command": "uvx",
      "args": ["capitalcom-mcp==0.3.4"],
      "env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
    }
  }
}

CLI 写法为 uvx capitalcom-mcp==0.3.4 run …。请锁定到已审核的版本，并在阅读 CHANGELOG 后再主动升级。

1. 添加凭据（仅需一次）

在 Capital.com 应用中获取 API 密钥：Settings → API integrations（先创建演示密钥）。然后运行向导——它会写入一个权限为 0600 的文件，并打印准确的客户端代码片段：

uvx capitalcom-mcp init

这会写入 ~/.config/capital-mcp/.env。可随时验证（不会打印机密信息）：

uvx capitalcom-mcp doctor

查看完整的生效配置（脱敏、离线），或确认凭据是否确实通过身份验证：

uvx capitalcom-mcp config          # effective settings + credential source
uvx capitalcom-mcp doctor --login  # verify authentication against the API

更倾向于使用密钥管理器？将 CAP_API_KEY_CMD / CAP_IDENTIFIER_CMD / CAP_API_PASSWORD_CMD 设为可打印密钥的命令（例如 op read op://vault/...、pass ...）。密钥会在启动时获取，绝不会写入磁盘或客户端配置。

2. 将服务添加到客户端

所有客户端都使用相同的 command/args/env 结构。粘贴 "CAP_ENV_FILE": "<path from init>" 可将机密信息留在客户端文件之外；也可以将 CAP_API_KEY/CAP_IDENTIFIER/CAP_API_PASSWORD 直接放入 env。

Claude Desktop

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

{
  "mcpServers": {
    "capitalcom": {
      "command": "uvx",
      "args": ["capitalcom-mcp"],
      "env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
    }
  }
}

Claude Code

claude mcp add --transport stdio \
  --env CAP_ENV_FILE=/Users/you/.config/capital-mcp/.env \
  capitalcom -- uvx capitalcom-mcp

Cursor

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

{
  "mcpServers": {
    "capitalcom": {
      "command": "uvx",
      "args": ["capitalcom-mcp"],
      "env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
    }
  }
}

VS Code（Copilot）

.vscode/mcp.json——注意根键为 servers，且 type: "stdio"：

{
  "servers": {
    "capitalcom": {
      "type": "stdio",
      "command": "uvx",
      "args": ["capitalcom-mcp"],
      "env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "capitalcom": {
      "command": "uvx",
      "args": ["capitalcom-mcp"],
      "env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
    }
  }
}

ChatGPT

ChatGPT 需要远程服务（不支持 stdio）——请参阅 远程 / VPS 托管。服务通过 HTTPS 可访问后，启用开发者模式（Settings → Connectors → Advanced），并添加以 /mcp 结尾的 服务 URL。ChatGPT Deep Research 连接器会调用此服务实现的两个只读工具 search 和 fetch；完整的自定义工具需要开发者模式。

远程 / VPS 托管

使用 streamable-HTTP 而不是 stdio 运行：

CAP_ENV_FILE=/home/you/.config/capital-mcp/.env \
  capitalcom-mcp run --transport http --host 0.0.0.0 --port 8000
# endpoint: http://<host>:8000/mcp

也可以通过环境变量设置（便于在 systemd 中使用）：CAP_MCP_TRANSPORT=http、CAP_MCP_HOST、 CAP_MCP_PORT。用于任何公共用途时，请将其置于终止 TLS 的反向代理之后。

内含内容——工具、资源与提示词

此服务提供 42 个工具、4 个资源和 7 个引导式提示词。除两个 ChatGPT Deep Research 适配器 （search、fetch）外，所有工具名称均以 cap_ 为前缀。修改类工具需要 confirm=true；交易分为两个阶段。 完整功能集是稳定的契约——请参阅 API 稳定性。

会话与账户

工具	功能
cap_session_status	当前登录 / 会话状态。
cap_session_login	身份验证（可选设置 force=true）。
cap_session_ping	保持连接 / 存活检查。
cap_session_logout	结束会话。
cap_session_switch_account	切换当前交易账户。
cap_account_list	列出账户和当前账户 ID。
cap_account_preferences_get	读取账户偏好设置（例如对冲模式）。
cap_account_preferences_set	更新偏好设置（需要 confirm）。
cap_account_history_activity	账户活动历史记录。
cap_account_history_transactions	交易历史记录。
cap_account_demo_topup	为模拟余额充值（需要 confirm）。

市场数据

工具	功能
cap_market_search	按搜索词搜索交易品种。
cap_market_get	获取 EPIC 的完整市场详情和快照。
cap_market_navigation_root	顶层市场导航节点。
cap_market_navigation_node	深入浏览某个导航节点。
cap_market_prices	历史 OHLC 蜡烛图数据。
cap_market_sentiment	客户多空仓位分布。

交易（读取 → 预览 → 执行 → 管理）

工具	功能
cap_trade_positions_list	未平仓头寸。
cap_trade_positions_get	按交易 ID 获取单个头寸。
cap_trade_orders_list	挂单。
cap_trade_confirm_get	按引用获取交易确认信息。
cap_trade_confirm_wait	轮询直至交易得到确认（或超时）。
cap_trade_preview_position	阶段 1：验证市场头寸（不执行）。
cap_trade_preview_working_order	阶段 1：验证挂单。
cap_trade_execute_position	阶段 2：执行预览过的头寸（需要 confirm）。
cap_trade_execute_working_order	阶段 2：提交预览过的挂单（需要 confirm）。
cap_trade_positions_close	平仓（需要 confirm）。
cap_trade_orders_cancel	取消挂单（需要 confirm）。
cap_trade_positions_amend	修改头寸的止损 / 限价（需要 confirm）。
cap_trade_orders_amend	修改挂单（需要 confirm）。

自选列表

工具	功能
cap_watchlists_list	列出自选列表。
cap_watchlists_get	获取某个自选列表中的市场。
cap_watchlists_create	创建自选列表（需要 confirm）。
cap_watchlists_add_market	添加 EPIC（需要 confirm）。
cap_watchlists_remove_market	移除 EPIC（需要 confirm）。
cap_watchlists_delete	删除自选列表（需要 confirm）。

流式数据（WebSocket；需要 CAP_WS_ENABLED=true）

工具	功能
cap_stream_prices	EPIC 的实时报价更新（买价 / 卖价）。
cap_stream_candles	实时 OHLC 蜡烛图更新。
cap_stream_alerts	价格阈值提醒。
cap_stream_portfolio	头寸 / 盈亏实时更新。

ChatGPT Deep Research 适配器

工具	功能
search	只读的工具搜索（ChatGPT 连接器约定）。
fetch	根据 ID 只读获取工具（ChatGPT 连接器约定）。

资源

URI	返回内容
cap://status	会话／连接状态快照。
cap://risk-policy	当前风险政策（交易标志、上限）。
cap://allowed-epics	交易 EPIC 允许列表。
cap://market-cache/{epic}	EPIC 的缓存市场快照。

引导提示词

提示词是客户端可按名称启动的可复用工作流。它们会发出分步指导，以编排上述工具——绝不会自行交易。

提示词	用途
market_scan	扫描关注列表，寻找机会（价格 + 市场情绪）。
trade_proposal	设计符合风险规模的交易，并通过预览进行验证。
execute_trade	安全执行此前已预览的交易。
position_review	审查未平仓头寸和有效订单。
live_price_monitor	实时推送价格，并标记达到阈值的变动。
real_time_alerts	配置并监控实时价格提醒。
live_portfolio_monitor	实时推送投资组合的盈亏，并设置阈值。

安全模型

• 除非 CAP_ALLOW_TRADING=true 且 EPIC 位于 CAP_ALLOWED_EPICS 中（或为 ALL），否则交易处于关闭状态。
• 两阶段执行；进行变更时必须设置 confirm=true。
• 设有规模、未平仓头寸和每日订单上限；CAP_DRY_RUN=true 会阻止所有执行。TIMEOUT 确认结果不明确——应先核对，切勿盲目重试。

开发

make install   # editable MCP + capitalcom-cli SDK from PyPI
make check     # ruff + mypy + pytest (offline; no network/credentials)

端到端测试会通过 MCP，针对 demo API 测试每个工具（读取、关注列表、账户切换、预览／执行／修改／平仓／取消、流式传输）。 测试会下真实的 demo 订单，并在完成后清理，因此请使用启用了交易和流式传输的 demo .env：

# demo .env: CAP_ALLOW_TRADING=true, CAP_ALLOWED_EPICS=GOLD, CAP_WS_ENABLED=true
CAP_MCP_E2E=1 pytest -m e2e -v

贡献

欢迎贡献——这是一个社区项目。请从 CONTRIBUTING.md 开始，浏览 适合新手的问题，并查看 路线图，了解项目的发展方向。架构和一个完整的“添加工具”示例见 docs/extending.md。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。