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:

hljs language-bash

uvx capitalcom-mcp --help        # smoke test

Or install a persistent command with pipx:

hljs language-bash

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:

hljs language-json

{
  "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:

hljs language-bash

uvx capitalcom-mcp init

This writes ~/.config/capital-mcp/.env. Verify any time (no secrets printed):

hljs language-bash

uvx capitalcom-mcp doctor

Inspect the full effective configuration (redacted, offline) or confirm your credentials actually authenticate:

hljs language-bash

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

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):

hljs language-json

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

Claude Code

hljs language-bash

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):

hljs language-json

{
  "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":

hljs language-json

{
  "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:

hljs language-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:

hljs language-bash

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=true and the EPIC is in CAP_ALLOWED_EPICS (or ALL).
Two-phase execution; confirm=true required for mutations.
Size, open-position, and daily-order caps; CAP_DRY_RUN=true blocks all executions. A TIMEOUT confirmation is ambiguous — reconcile, don't blindly retry.

Development

hljs language-bash

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:

hljs language-bash

# 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.

License

Apache-2.0. See LICENSE and NOTICE.

Capital.com MCP Server

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:

hljs language-bash

uvx capitalcom-mcp --help        # smoke test

Or install a persistent command with pipx:

hljs language-bash

pipx install capitalcom-mcp

Pinning for production / real-money use

hljs language-json

{
  "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:

hljs language-bash

uvx capitalcom-mcp init

This writes ~/.config/capital-mcp/.env. Verify any time (no secrets printed):

hljs language-bash

uvx capitalcom-mcp doctor

Inspect the full effective configuration (redacted, offline) or confirm your credentials actually authenticate:

hljs language-bash

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

2. Add the server to your client

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

hljs language-json

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

Claude Code

hljs language-bash

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):

hljs language-json

{
  "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":

hljs language-json

{
  "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:

hljs language-json

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

ChatGPT

Remote / VPS hosting

Run with streamable-HTTP instead of stdio:

hljs language-bash

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

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=true and the EPIC is in CAP_ALLOWED_EPICS (or ALL).
Two-phase execution; confirm=true required for mutations.
Size, open-position, and daily-order caps; CAP_DRY_RUN=true blocks all executions. A TIMEOUT confirmation is ambiguous — reconcile, don't blindly retry.

Development

hljs language-bash

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

hljs language-bash

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

Contributing

License

Apache-2.0. See LICENSE and NOTICE.

capitalcom-mcp-server

Capital.com MCP Server

Install

Pinning for production / real-money use

1. Add your credentials (once)

2. Add the server to your client

Claude Desktop

Claude Code

Cursor

VS Code (Copilot)

Windsurf

ChatGPT

Remote / VPS hosting

What's inside — tools, resources & prompts

Session & account

Market data

Trading (read → preview → execute → manage)

Watchlists

Streaming (WebSocket; requires CAP_WS_ENABLED=true)

ChatGPT Deep Research adapters

Resources

Guided prompts

Safety model

Development

Contributing

License

Similar Packages

capitalcom-mcp-server

Capital.com MCP Server

Install

Pinning for production / real-money use

1. Add your credentials (once)

2. Add the server to your client

Claude Desktop

Claude Code

Cursor

VS Code (Copilot)

Windsurf

ChatGPT

Remote / VPS hosting

What's inside — tools, resources & prompts

Session & account

Market data

Trading (read → preview → execute → manage)

Watchlists

Streaming (WebSocket; requires CAP_WS_ENABLED=true)

ChatGPT Deep Research adapters

Resources

Guided prompts

Safety model

Development

Contributing

License

Similar Packages

Streaming (WebSocket; requires `CAP_WS_ENABLED=true`)

Streaming (WebSocket; requires `CAP_WS_ENABLED=true`)