<!-- mcp-name: io.github.SimonTarara62/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.

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

Market data

Trading (read → preview → execute → manage)

Watchlists

Streaming (WebSocket; requires CAP_WS_ENABLED=true)

ChatGPT Deep Research adapters

Resources

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.

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.