Skip to main content
Glama
capitalcom-mcp-server

capitalcom-mcp-server

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.

PyPI version Python versions CI License: Apache-2.0 MCP Registry Glama quality score PyPI downloads

⚠️ 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.

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 init

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

uvx capitalcom-mcp doctor

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

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

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.

License

Apache-2.0. See LICENSE and NOTICE.

Available Tools

42 tools
cap_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_navigation_nodeB

Get child nodes/markets under a navigation node.

Inputs: node_id (required). Returns: object

cap_market_navigation_rootA

Get the root market-navigation tree (categories).

Inputs: no named parameters. 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_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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 42 tools

    Disambiguation5/5

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

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A 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 v3
      3
      50 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables interaction with the Tradovate API for managing trading contracts, positions, orders, and accounts.
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Alpaca’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 IDEs
      72
      19,012 PyPI
      1,086
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
      -