capitalcom-mcp-server
A self-hosted MCP server that connects AI assistants to the Capital.com trading platform, exposing 42 tools for market data, trading, watchlists, and live streaming — all with built-in safety guards.
Session & Account Management
Check, create, maintain, and end trading sessions; switch between accounts
List accounts, view balances, read/update preferences (hedging mode, leverage)
View activity/transaction history; top up a demo account balance
Market Data
Search instruments by name or EPIC; get full market details and dealing rules
Browse the market navigation tree; retrieve historical OHLC candlestick data (e.g., MINUTE_15, HOUR, DAY)
Get client sentiment data (long vs. short positioning)
Trading (Two-Phase, Safety-Gated)
Preview (Phase 1): Validate market positions and working orders with no side effects
Execute (Phase 2): Place real positions or working orders (requires
confirm=true)List/inspect open positions and pending orders; close positions; cancel/amend working orders
Amend stop-loss/take-profit on positions; fetch and poll deal confirmations
Watchlists
List, create, and delete watchlists; view, add, or remove instruments (EPICs)
Live Streaming (WebSocket)
Stream live bid/ask prices (up to 40 instruments), live OHLC candles, price threshold alerts, and portfolio P&L updates (requires
CAP_WS_ENABLED=true)
ChatGPT Deep Research Adapters
search: Read-only instrument search compatible with ChatGPT connector contractfetch: Read-only instrument detail fetch by ID
Safety Features
Trading disabled by default; requires explicit opt-in via environment variables
All mutating operations require
confirm=true; dry-run mode blocks all executionsEPIC allowlists, size caps, open-position limits, and daily-order limits
Demo account support for risk-free testing
Guided Prompts: Seven built-in workflow prompts for market scanning, trade proposals, position review, live monitoring, and more.
Provides tools for Capital.com trading and market data, compatible with Windsurf (Codeium's IDE).
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 testOr install a persistent command with pipx:
pipx install capitalcom-mcpPinning 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.
Related MCP server: Tradovate MCP Server
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 initThis writes ~/.config/capital-mcp/.env. Verify any time (no secrets printed):
uvx capitalcom-mcp doctorInspect the full effective configuration (redacted, offline) or confirm your credentials actually authenticate:
uvx capitalcom-mcp config # effective settings + credential source
uvx capitalcom-mcp doctor --login # verify authentication against the APIPrefer 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-mcpCursor
~/.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/mcpOr 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 |
| Current login/session state. |
| Authenticate (optionally |
| Keep-alive / liveness check. |
| End the session. |
| Switch the active trading account. |
| List accounts and the active account id. |
| Read account preferences (e.g. hedging mode). |
| Update preferences ( |
| Account activity history. |
| Transaction history. |
| Top up a demo balance ( |
Market data
Tool | What it does |
| Search instruments by term. |
| Full market details + snapshot for an EPIC. |
| Top-level market navigation nodes. |
| Drill into a navigation node. |
| Historical OHLC candles. |
| Client long/short positioning. |
Trading (read → preview → execute → manage)
Tool | What it does |
| Open positions. |
| One position by deal id. |
| Working (pending) orders. |
| Fetch a deal confirmation by reference. |
| Poll until a deal confirms (or times out). |
| Phase 1: validate a market position (no execution). |
| Phase 1: validate a working order. |
| Phase 2: execute a previewed position ( |
| Phase 2: place a previewed working order ( |
| Close a position ( |
| Cancel a working order ( |
| Amend stop/limit on a position ( |
| Amend a working order ( |
Watchlists
Tool | What it does |
| List watchlists. |
| Get one watchlist's markets. |
| Create a watchlist ( |
| Add an EPIC ( |
| Remove an EPIC ( |
| Delete a watchlist ( |
Streaming (WebSocket; requires CAP_WS_ENABLED=true)
Tool | What it does |
| Live bid/ask updates for EPICs. |
| Live OHLC candle updates. |
| Threshold price alerts. |
| Live position/P&L updates. |
ChatGPT Deep Research adapters
Tool | What it does |
| Read-only instrument search (ChatGPT connector contract). |
| Read-only instrument fetch by id (ChatGPT connector contract). |
Resources
URI | What it returns |
| Session/connection status snapshot. |
| Active risk policy (trading flag, caps). |
| The trading EPIC allowlist. |
| 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 |
| Scan a watchlist for opportunities (prices + sentiment). |
| Design a risk-sized trade and validate it via preview. |
| Safely execute a previously previewed trade. |
| Review open positions and working orders. |
| Stream prices and flag threshold moves. |
| Configure and watch live price alerts. |
| 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 -vContributing
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
Available Tools
42 toolscap_account_demo_topupA
Top up the demo account balance (DEMO ONLY). The SDK enforces demo + confirm.
Inputs: amount (required), confirm. Returns: object
cap_account_history_activityA
Get account activity history (deals, orders, updates). detailed adds fields; deal_id filters.
Inputs: from_date, to_date, last_period, detailed, +1 more. Returns: object
cap_account_history_transactionsC
Get transaction history (deposits, withdrawals, P&L). Optional type filter.
Inputs: from_date, to_date, last_period, type. Returns: object
cap_account_listA
List all trading accounts (balance, currency, type). Requires authentication.
Inputs: no named parameters. Returns: object
cap_account_preferences_getB
Get account preferences (hedging mode, per-asset-class leverage).
Inputs: no named parameters. Returns: object
cap_account_preferences_setC
Set account preferences (TRADE-GATED). Requires confirm=true when configured.
Inputs: hedging_mode, leverages, confirm. Returns: object
cap_market_getA
Get full market details and dealing rules for an EPIC.
Inputs: epic (required). Returns: object
cap_market_pricesC
Get historical OHLC candles. resolution e.g. MINUTE_15, HOUR, DAY.
Inputs: epic (required), resolution, max, from_date, +1 more. Returns: object
cap_market_searchC
Search markets by term or EPIC list. limit truncates results client-side.
Inputs: search_term, epics, limit. Returns: object
cap_market_sentimentC
Get client sentiment (long vs short %) for a market.
Inputs: market_id (required). Returns: object
cap_session_loginC
Create or verify a session. force=true re-logs in; account_id switches account.
Inputs: force, account_id. Returns: object
cap_session_logoutA
End the session and clear tokens. Requires authentication.
Inputs: no named parameters. Returns: object
cap_session_pingA
Keep the session alive (extends timeout). Requires authentication.
Inputs: no named parameters. Returns: object
cap_session_statusA
Get current session status (login state, account, token expiry). No auth required.
Inputs: no named parameters. Returns: object
cap_session_switch_accountA
Switch the active trading account by ID. Requires authentication.
Inputs: account_id (required). Returns: object
cap_stream_alertsC
Monitor EPICs for price-level crossings. alerts: {EPIC: {level, direction: ABOVE|BELOW}}.
Inputs: alerts (required), duration_s, auto_close. Returns: object
cap_stream_candlesA
Stream live OHLC bars for up to 40 EPICs at the given resolutions (WebSocket).
resolutions e.g. ["MINUTE", "HOUR"]; bar_type "classic" or "heikin-ashi".
Inputs: epics (required), resolutions (required), bar_type, duration_s, +1 more. Returns: object
cap_stream_portfolioB
Stream live portfolio snapshots for open positions for duration_s seconds (WebSocket).
Inputs: duration_s, update_interval_s. Returns: object
cap_stream_pricesB
Stream live bid/offer for up to 40 EPICs for duration_s seconds (WebSocket).
Inputs: epics (required), duration_s, update_interval_s. Returns: object
cap_trade_confirm_getA
Get deal-confirmation status (ACCEPTED/REJECTED/pending) for a deal reference.
Inputs: deal_reference (required). Returns: object
cap_trade_confirm_waitA
Poll the confirmation endpoint until ACCEPTED/REJECTED or timeout.
Inputs: deal_reference (required), timeout_s, poll_interval_ms. Returns: object
cap_trade_execute_positionB
Execute a previewed position (CREATES A REAL TRADE). SDK enforces all safety gates.
Inputs: preview_id (required), confirm, wait_for_confirm, timeout_s. Returns: object
cap_trade_execute_working_orderA
Execute a previewed working order (CREATES A REAL ORDER). SDK enforces all safety gates.
Inputs: preview_id (required), confirm, wait_for_confirm, timeout_s. Returns: object
cap_trade_orders_amendA
Amend a working order's level/expiry/stops-limits (SIDE EFFECT). Requires confirm.
Inputs: deal_id (required), level, stop_level, stop_distance, +6 more. Returns: object
cap_trade_orders_cancelA
Cancel a working order (SIDE EFFECT). Requires confirm + trading enabled.
Inputs: deal_id (required), confirm, wait_for_confirm, timeout_s. Returns: object
cap_trade_orders_listA
List all working orders (pending LIMIT/STOP that haven't triggered).
Inputs: no named parameters. Returns: object
cap_trade_positions_amendB
Amend stop-loss / take-profit on an open position (SIDE EFFECT). Requires confirm.
Inputs: deal_id (required), stop_level, stop_distance, profit_level, +6 more. Returns: object
cap_trade_positions_closeB
Close an open position (SIDE EFFECT). Requires confirm + trading enabled.
Inputs: deal_id (required), confirm, wait_for_confirm, timeout_s. Returns: object
cap_trade_positions_getA
Get a single position's details by deal ID.
Inputs: deal_id (required). Returns: object
cap_trade_positions_listA
List all open positions (P&L, direction, size, attached orders).
Inputs: no named parameters. Returns: object
cap_trade_preview_positionA
Preview a position (NO SIDE EFFECTS). Runs the full risk pipeline; returns preview_id.
Inputs: epic (required), direction (required), size (required), guaranteed_stop, +7 more. Returns: object
cap_trade_preview_working_orderA
Preview a working order (NO SIDE EFFECTS). type is LIMIT or STOP. Returns preview_id.
Inputs: epic (required), direction (required), type (required), level (required), +10 more. Returns: object
cap_watchlists_add_marketC
Add a market (EPIC) to a watchlist. Requires confirm when configured.
Inputs: watchlist_id (required), epic (required), confirm. Returns: object
cap_watchlists_createB
Create a new watchlist (1-100 chars). Requires confirm when configured.
Inputs: name (required), confirm. Returns: object
cap_watchlists_deleteC
Delete a watchlist. Requires confirm when configured.
Inputs: watchlist_id (required), confirm. Returns: object
cap_watchlists_getC
Get a watchlist's details including its markets.
Inputs: watchlist_id (required). Returns: object
cap_watchlists_listA
List all watchlists (IDs and names).
Inputs: no named parameters. Returns: object
cap_watchlists_remove_marketB
Remove a market (EPIC) from a watchlist. Requires confirm when configured.
Inputs: watchlist_id (required), epic (required), confirm. Returns: object
fetchC
ChatGPT Deep Research: fetch a market's details. Returns {id,title,text,url,metadata}.
Inputs: id (required). Returns: object
searchC
ChatGPT Deep Research: search Capital.com markets. Returns {results:[{id,title,url}]}.
Inputs: query (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Each tool targets a distinct operation within its domain (account, market, session, stream, trade, watchlists). Descriptions clearly differentiate between similar tools (e.g., preview vs execute, history activity vs transactions).
The vast majority follow a consistent `cap_<domain>_<action>` pattern, but two plain-named tools (`fetch` and `search`) without the prefix break the pattern significantly, lowering consistency.
42 tools is high but justifiable for a full-featured trading platform covering account, market, session, streams, trades, and watchlists. Slightly above typical range but well-scoped.
The tool set covers the full lifecycle: account management, market data, session handling, real-time streaming, trade preview/execute/amend/close, order management, and watchlists. No obvious gaps for typical trading workflows.
Maintenance
Related MCP Connectors
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
A Model Context Protocol server for Wix AI tools
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityCmaintenanceA Model Context Protocol (MCP) server that provides comprehensive cryptocurrency analysis using the CoinCap API. This server offers real-time price data, market analysis, and historical trends through an easy-to-use interface. Updated to use Coin Cap API v3350 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables interaction with the Tradovate API for managing trading contracts, positions, orders, and accounts.1MIT

alpaca-mcp-serverofficial
AlicenseBqualityBmaintenanceAlpaca’s official MCP Server lets you trade stocks, ETFs, crypto, and options, run data analysis, and build strategies in plain English directly from your favorite LLM tools and IDEs7219,012 PyPI1,086MIT- FlicenseNot gradedqualityDmaintenanceProvides foundational trading utilities by fetching market data through Akshare and computing technical indicators like RSI and MACD using TA-Lib. It enables users to retrieve candlestick data and technical analysis series via a standardized MCP interface.9-