Capital.com MCP Server
Self-hosted Model Context Protocol (MCP) server for the Capital.com Open
API, written in Python on FastMCP. It
exposes 42 safe, guarded trading and market-data tools — two-phase
execution, allowlists, demo-first — to any MCP client, over stdio or HTTP. Built
on the tested capitalcom-cli
broker engine (SDK).
Works with Claude Desktop · Claude Code · Cursor · VS Code (Copilot) · Windsurf · ChatGPT — any MCP client.
⚠️ Unofficial & educational. Not affiliated with Capital.com. Trading is risky and this is not financial advice. Trading is disabled by default; all trades are two-phase (preview → confirm → execute) with allowlists and size/rate limits. Start on a demo account. Apache-2.0 licensed.
Install
No clone required — uvx runs it in an isolated, throwaway environment and
always fetches the latest tested release:
uvx capitalcom-mcp --help # smoke test
Or install a persistent command with pipx:
pipx install capitalcom-mcp
Pinning for production / real-money use
uvx capitalcom-mcp always runs the latest published release. That is fine
for trying it out, but for production or real-money use, pin the exact
version so an unexpected update can't change tool behavior under you:
{
"mcpServers": {
"capitalcom": {
"command": "uvx",
"args": ["capitalcom-mcp==0.3.4"],
"env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
}
}
}
The CLI form is uvx capitalcom-mcp==0.3.4 run …. Pin to a version you have
reviewed, and bump deliberately after reading the CHANGELOG.
1. Add your credentials (once)
Get an API key in the Capital.com app: Settings → API integrations (make a
demo key first). Then run the wizard — it writes a 0600 file and prints
the exact client snippet:
uvx capitalcom-mcp init
This writes ~/.config/capital-mcp/.env. Verify any time (no secrets printed):
uvx capitalcom-mcp doctor
Prefer a secret manager? Set CAP_API_KEY_CMD / CAP_IDENTIFIER_CMD /
CAP_API_PASSWORD_CMD to a command that prints the secret (e.g.
op read op://vault/..., pass ...). The secret is fetched at launch and never
written to disk or to your client config.
2. Add the server to your client
Every client uses the same command/args/env shape. Pasting
"CAP_ENV_FILE": "<path from init>" keeps secrets out of the client file; or
put CAP_API_KEY/CAP_IDENTIFIER/CAP_API_PASSWORD directly in 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 (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"capitalcom": {
"command": "uvx",
"args": ["capitalcom-mcp"],
"env": { "CAP_ENV_FILE": "/Users/you/.config/capital-mcp/.env" }
}
}
}
VS Code (Copilot)
.vscode/mcp.json — note the root key is servers and 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 requires a remote server (stdio is not supported) — see
Remote / VPS hosting. Once your server is reachable over
HTTPS, enable Developer Mode (Settings → Connectors → Advanced) and add the
server URL ending in /mcp. ChatGPT Deep Research connectors call two
read-only tools, search and fetch, which this server implements; full custom
tools require Developer Mode.
Remote / VPS hosting
Run with streamable-HTTP instead of 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
Or via env (handy in systemd): CAP_MCP_TRANSPORT=http, CAP_MCP_HOST,
CAP_MCP_PORT. Put it behind a TLS-terminating reverse proxy for any public use.
What's inside — tools, resources & prompts
This server exposes 42 tools, 4 resources, and 7 guided prompts. All
tool names are prefixed cap_ except the two ChatGPT Deep Research adapters
(search, fetch). Mutating tools require confirm=true; trades are two-phase.
The full surface is a stable contract — see API stability.
Session & account
| Tool | What it does |
|---|---|
cap_session_status | Current login/session state. |
cap_session_login | Authenticate (optionally force=true). |
cap_session_ping | Keep-alive / liveness check. |
cap_session_logout | End the session. |
cap_session_switch_account | Switch the active trading account. |
cap_account_list | List accounts and the active account id. |
cap_account_preferences_get | Read account preferences (e.g. hedging mode). |
cap_account_preferences_set | Update preferences (confirm required). |
cap_account_history_activity | Account activity history. |
cap_account_history_transactions | Transaction history. |
cap_account_demo_topup | Top up a demo balance (confirm required). |
Market data
| Tool | What it does |
|---|---|
cap_market_search | Search instruments by term. |
cap_market_get | Full market details + snapshot for an EPIC. |
cap_market_navigation_root | Top-level market navigation nodes. |
cap_market_navigation_node | Drill into a navigation node. |
cap_market_prices | Historical OHLC candles. |
cap_market_sentiment | Client long/short positioning. |
Trading (read → preview → execute → manage)
| Tool | What it does |
|---|---|
cap_trade_positions_list | Open positions. |
cap_trade_positions_get | One position by deal id. |
cap_trade_orders_list | Working (pending) orders. |
cap_trade_confirm_get | Fetch a deal confirmation by reference. |
cap_trade_confirm_wait | Poll until a deal confirms (or times out). |
cap_trade_preview_position | Phase 1: validate a market position (no execution). |
cap_trade_preview_working_order | Phase 1: validate a working order. |
cap_trade_execute_position | Phase 2: execute a previewed position (confirm). |
cap_trade_execute_working_order | Phase 2: place a previewed working order (confirm). |
cap_trade_positions_close | Close a position (confirm). |
cap_trade_orders_cancel | Cancel a working order (confirm). |
cap_trade_positions_amend | Amend stop/limit on a position (confirm). |
cap_trade_orders_amend | Amend a working order (confirm). |
Watchlists
| Tool | What it does |
|---|---|
cap_watchlists_list | List watchlists. |
cap_watchlists_get | Get one watchlist's markets. |
cap_watchlists_create | Create a watchlist (confirm). |
cap_watchlists_add_market | Add an EPIC (confirm). |
cap_watchlists_remove_market | Remove an EPIC (confirm). |
cap_watchlists_delete | Delete a watchlist (confirm). |
Streaming (WebSocket; requires CAP_WS_ENABLED=true)
| Tool | What it does |
|---|---|
cap_stream_prices | Live bid/ask updates for EPICs. |
cap_stream_candles | Live OHLC candle updates. |
cap_stream_alerts | Threshold price alerts. |
cap_stream_portfolio | Live position/P&L updates. |
ChatGPT Deep Research adapters
| Tool | What it does |
|---|---|
search | Read-only instrument search (ChatGPT connector contract). |
fetch | Read-only instrument fetch by id (ChatGPT connector contract). |
Resources
| URI | What it returns |
|---|---|
cap://status | Session/connection status snapshot. |
cap://risk-policy | Active risk policy (trading flag, caps). |
cap://allowed-epics | The trading EPIC allowlist. |
cap://market-cache/{epic} | Cached market snapshot for an EPIC. |
Guided prompts
Prompts are reusable workflows your client can launch by name. They emit step-by-step guidance that orchestrates the tools above — they never trade on their own.
| Prompt | Purpose |
|---|---|
market_scan | Scan a watchlist for opportunities (prices + sentiment). |
trade_proposal | Design a risk-sized trade and validate it via preview. |
execute_trade | Safely execute a previously previewed trade. |
position_review | Review open positions and working orders. |
live_price_monitor | Stream prices and flag threshold moves. |
real_time_alerts | Configure and watch live price alerts. |
live_portfolio_monitor | Stream live portfolio P&L with a threshold. |
Safety model
- Trading off unless
CAP_ALLOW_TRADING=trueand the EPIC is inCAP_ALLOWED_EPICS(orALL). - Two-phase execution;
confirm=truerequired for mutations. - Size, open-position, and daily-order caps;
CAP_DRY_RUN=trueblocks all executions. ATIMEOUTconfirmation is ambiguous — reconcile, don't blindly retry.
Development
make install # editable MCP + capitalcom-cli SDK from PyPI
make check # ruff + mypy + pytest (offline; no network/credentials)
End-to-end tests drive every tool through the MCP against the demo API
(read, watchlists, account switch, preview/execute/amend/close/cancel, streaming).
They place real demo orders and clean up after themselves, so use a demo .env
with trading + streaming enabled:
# demo .env: CAP_ALLOW_TRADING=true, CAP_ALLOWED_EPICS=GOLD, CAP_WS_ENABLED=true
CAP_MCP_E2E=1 pytest -m e2e -v
Contributing
Contributions are welcome — this is a community project. Start with CONTRIBUTING.md, browse good first issues, and see the roadmap for where it's heading. The architecture and a worked "add a tool" example are in docs/extending.md.