{
  "markdown": "<!-- mcp-name: io.github.SimonTarara62/capitalcom-mcp-server -->\n\n# Capital.com MCP Server\n\nSelf-hosted **Model Context Protocol (MCP)** server for the **Capital.com Open\nAPI**, written in Python on [FastMCP](https://github.com/jlowin/fastmcp). It\nexposes **42 safe, guarded trading and market-data tools** — two-phase\nexecution, allowlists, demo-first — to any MCP client, over stdio or HTTP. Built\non the tested [`capitalcom-cli`](https://github.com/SimonTarara62/capitalcom-cli)\nbroker engine (SDK).\n\n**Works with** Claude Desktop · Claude Code · Cursor · VS Code (Copilot) ·\nWindsurf · ChatGPT — any MCP client.\n\n[![PyPI version](https://img.shields.io/pypi/v/capitalcom-mcp.svg)](https://pypi.org/project/capitalcom-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/capitalcom-mcp.svg)](https://pypi.org/project/capitalcom-mcp/)\n[![CI](https://github.com/SimonTarara62/capitalcom-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/SimonTarara62/capitalcom-mcp-server/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0098FF)](https://registry.modelcontextprotocol.io/?search=io.github.SimonTarara62/capitalcom-mcp-server)\n[![Glama quality score](https://glama.ai/mcp/servers/nmcob5apit/badges/score.svg)](https://glama.ai/mcp/servers/nmcob5apit)\n[![PyPI downloads](https://img.shields.io/pypi/dm/capitalcom-mcp.svg)](https://pypi.org/project/capitalcom-mcp/)\n\n> ⚠️ **Unofficial & educational.** Not affiliated with Capital.com. Trading is\n> risky and this is not financial advice. Trading is **disabled by default**;\n> all trades are two-phase (preview → confirm → execute) with allowlists and\n> size/rate limits. Start on a **demo** account. Apache-2.0 licensed.\n\n## Install\n\nNo clone required — `uvx` runs it in an isolated, throwaway environment and\nalways fetches the latest tested release:\n\n```bash\nuvx capitalcom-mcp --help        # smoke test\n```\n\nOr install a persistent command with pipx:\n\n```bash\npipx install capitalcom-mcp\n```\n\n### Pinning for production / real-money use\n\n`uvx capitalcom-mcp` always runs the **latest** published release. That is fine\nfor trying it out, but for production or real-money use, **pin the exact\nversion** so an unexpected update can't change tool behavior under you:\n\n```json\n{\n  \"mcpServers\": {\n    \"capitalcom\": {\n      \"command\": \"uvx\",\n      \"args\": [\"capitalcom-mcp==0.3.4\"],\n      \"env\": { \"CAP_ENV_FILE\": \"/Users/you/.config/capital-mcp/.env\" }\n    }\n  }\n}\n```\n\nThe CLI form is `uvx capitalcom-mcp==0.3.4 run …`. Pin to a version you have\nreviewed, and bump deliberately after reading the [CHANGELOG](CHANGELOG.md).\n\n## 1. Add your credentials (once)\n\nGet an API key in the Capital.com app: **Settings → API integrations** (make a\n**demo** key first). Then run the wizard — it writes a `0600` file and prints\nthe exact client snippet:\n\n```bash\nuvx capitalcom-mcp init\n```\n\nThis writes `~/.config/capital-mcp/.env`. Verify any time (no secrets printed):\n\n```bash\nuvx capitalcom-mcp doctor\n```\n\nInspect the full effective configuration (redacted, offline) or confirm your\ncredentials actually authenticate:\n\n```bash\nuvx capitalcom-mcp config          # effective settings + credential source\nuvx capitalcom-mcp doctor --login  # verify authentication against the API\n```\n\nPrefer a secret manager? Set `CAP_API_KEY_CMD` / `CAP_IDENTIFIER_CMD` /\n`CAP_API_PASSWORD_CMD` to a command that prints the secret (e.g.\n`op read op://vault/...`, `pass ...`). The secret is fetched at launch and never\nwritten to disk or to your client config.\n\n## 2. Add the server to your client\n\nEvery client uses the same `command`/`args`/`env` shape. Pasting\n`\"CAP_ENV_FILE\": \"<path from init>\"` keeps secrets out of the client file; or\nput `CAP_API_KEY`/`CAP_IDENTIFIER`/`CAP_API_PASSWORD` directly in `env`.\n\n### Claude Desktop\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) /\n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"capitalcom\": {\n      \"command\": \"uvx\",\n      \"args\": [\"capitalcom-mcp\"],\n      \"env\": { \"CAP_ENV_FILE\": \"/Users/you/.config/capital-mcp/.env\" }\n    }\n  }\n}\n```\n\n### Claude Code\n```bash\nclaude mcp add --transport stdio \\\n  --env CAP_ENV_FILE=/Users/you/.config/capital-mcp/.env \\\n  capitalcom -- uvx capitalcom-mcp\n```\n\n### Cursor\n`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"capitalcom\": {\n      \"command\": \"uvx\",\n      \"args\": [\"capitalcom-mcp\"],\n      \"env\": { \"CAP_ENV_FILE\": \"/Users/you/.config/capital-mcp/.env\" }\n    }\n  }\n}\n```\n\n### VS Code (Copilot)\n`.vscode/mcp.json` — note the root key is `servers` and `type: \"stdio\"`:\n\n```json\n{\n  \"servers\": {\n    \"capitalcom\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"capitalcom-mcp\"],\n      \"env\": { \"CAP_ENV_FILE\": \"/Users/you/.config/capital-mcp/.env\" }\n    }\n  }\n}\n```\n\n### Windsurf\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"capitalcom\": {\n      \"command\": \"uvx\",\n      \"args\": [\"capitalcom-mcp\"],\n      \"env\": { \"CAP_ENV_FILE\": \"/Users/you/.config/capital-mcp/.env\" }\n    }\n  }\n}\n```\n\n### ChatGPT\nChatGPT requires a **remote** server (stdio is not supported) — see\n[Remote / VPS hosting](#remote--vps-hosting). Once your server is reachable over\nHTTPS, enable **Developer Mode** (Settings → Connectors → Advanced) and add the\nserver URL ending in `/mcp`. ChatGPT **Deep Research** connectors call two\nread-only tools, `search` and `fetch`, which this server implements; full custom\ntools require Developer Mode.\n\n## Remote / VPS hosting\n\nRun with streamable-HTTP instead of stdio:\n\n```bash\nCAP_ENV_FILE=/home/you/.config/capital-mcp/.env \\\n  capitalcom-mcp run --transport http --host 0.0.0.0 --port 8000\n# endpoint: http://<host>:8000/mcp\n```\n\nOr via env (handy in systemd): `CAP_MCP_TRANSPORT=http`, `CAP_MCP_HOST`,\n`CAP_MCP_PORT`. Put it behind a TLS-terminating reverse proxy for any public use.\n\n## What's inside — tools, resources & prompts\n\nThis server exposes **42 tools**, **4 resources**, and **7 guided prompts**. All\ntool names are prefixed `cap_` except the two ChatGPT Deep Research adapters\n(`search`, `fetch`). Mutating tools require `confirm=true`; trades are two-phase.\nThe full surface is a stable contract — see [API stability](docs/api-stability.md).\n\n### Session & account\n\n| Tool | What it does |\n| --- | --- |\n| `cap_session_status` | Current login/session state. |\n| `cap_session_login` | Authenticate (optionally `force=true`). |\n| `cap_session_ping` | Keep-alive / liveness check. |\n| `cap_session_logout` | End the session. |\n| `cap_session_switch_account` | Switch the active trading account. |\n| `cap_account_list` | List accounts and the active account id. |\n| `cap_account_preferences_get` | Read account preferences (e.g. hedging mode). |\n| `cap_account_preferences_set` | Update preferences (`confirm` required). |\n| `cap_account_history_activity` | Account activity history. |\n| `cap_account_history_transactions` | Transaction history. |\n| `cap_account_demo_topup` | Top up a **demo** balance (`confirm` required). |\n\n### Market data\n\n| Tool | What it does |\n| --- | --- |\n| `cap_market_search` | Search instruments by term. |\n| `cap_market_get` | Full market details + snapshot for an EPIC. |\n| `cap_market_navigation_root` | Top-level market navigation nodes. |\n| `cap_market_navigation_node` | Drill into a navigation node. |\n| `cap_market_prices` | Historical OHLC candles. |\n| `cap_market_sentiment` | Client long/short positioning. |\n\n### Trading (read → preview → execute → manage)\n\n| Tool | What it does |\n| --- | --- |\n| `cap_trade_positions_list` | Open positions. |\n| `cap_trade_positions_get` | One position by deal id. |\n| `cap_trade_orders_list` | Working (pending) orders. |\n| `cap_trade_confirm_get` | Fetch a deal confirmation by reference. |\n| `cap_trade_confirm_wait` | Poll until a deal confirms (or times out). |\n| `cap_trade_preview_position` | **Phase 1**: validate a market position (no execution). |\n| `cap_trade_preview_working_order` | **Phase 1**: validate a working order. |\n| `cap_trade_execute_position` | **Phase 2**: execute a previewed position (`confirm`). |\n| `cap_trade_execute_working_order` | **Phase 2**: place a previewed working order (`confirm`). |\n| `cap_trade_positions_close` | Close a position (`confirm`). |\n| `cap_trade_orders_cancel` | Cancel a working order (`confirm`). |\n| `cap_trade_positions_amend` | Amend stop/limit on a position (`confirm`). |\n| `cap_trade_orders_amend` | Amend a working order (`confirm`). |\n\n### Watchlists\n\n| Tool | What it does |\n| --- | --- |\n| `cap_watchlists_list` | List watchlists. |\n| `cap_watchlists_get` | Get one watchlist's markets. |\n| `cap_watchlists_create` | Create a watchlist (`confirm`). |\n| `cap_watchlists_add_market` | Add an EPIC (`confirm`). |\n| `cap_watchlists_remove_market` | Remove an EPIC (`confirm`). |\n| `cap_watchlists_delete` | Delete a watchlist (`confirm`). |\n\n### Streaming (WebSocket; requires `CAP_WS_ENABLED=true`)\n\n| Tool | What it does |\n| --- | --- |\n| `cap_stream_prices` | Live bid/ask updates for EPICs. |\n| `cap_stream_candles` | Live OHLC candle updates. |\n| `cap_stream_alerts` | Threshold price alerts. |\n| `cap_stream_portfolio` | Live position/P&L updates. |\n\n### ChatGPT Deep Research adapters\n\n| Tool | What it does |\n| --- | --- |\n| `search` | Read-only instrument search (ChatGPT connector contract). |\n| `fetch` | Read-only instrument fetch by id (ChatGPT connector contract). |\n\n### Resources\n\n| URI | What it returns |\n| --- | --- |\n| `cap://status` | Session/connection status snapshot. |\n| `cap://risk-policy` | Active risk policy (trading flag, caps). |\n| `cap://allowed-epics` | The trading EPIC allowlist. |\n| `cap://market-cache/{epic}` | Cached market snapshot for an EPIC. |\n\n### Guided prompts\n\nPrompts are reusable workflows your client can launch by name. They emit\nstep-by-step guidance that orchestrates the tools above — they never trade on\ntheir own.\n\n| Prompt | Purpose |\n| --- | --- |\n| `market_scan` | Scan a watchlist for opportunities (prices + sentiment). |\n| `trade_proposal` | Design a risk-sized trade and validate it via preview. |\n| `execute_trade` | Safely execute a previously previewed trade. |\n| `position_review` | Review open positions and working orders. |\n| `live_price_monitor` | Stream prices and flag threshold moves. |\n| `real_time_alerts` | Configure and watch live price alerts. |\n| `live_portfolio_monitor` | Stream live portfolio P&L with a threshold. |\n\n## Safety model\n- Trading off unless `CAP_ALLOW_TRADING=true` **and** the EPIC is in\n  `CAP_ALLOWED_EPICS` (or `ALL`).\n- Two-phase execution; `confirm=true` required for mutations.\n- Size, open-position, and daily-order caps; `CAP_DRY_RUN=true` blocks all\n  executions. A `TIMEOUT` confirmation is ambiguous — reconcile, don't blindly retry.\n\n## Development\n```bash\nmake install   # editable MCP + capitalcom-cli SDK from PyPI\nmake check     # ruff + mypy + pytest (offline; no network/credentials)\n```\n\nEnd-to-end tests drive **every** tool through the MCP against the **demo** API\n(read, watchlists, account switch, preview/execute/amend/close/cancel, streaming).\nThey place real demo orders and clean up after themselves, so use a demo `.env`\nwith trading + streaming enabled:\n\n```bash\n# demo .env: CAP_ALLOW_TRADING=true, CAP_ALLOWED_EPICS=GOLD, CAP_WS_ENABLED=true\nCAP_MCP_E2E=1 pytest -m e2e -v\n```\n\n## Contributing\n\nContributions are welcome — this is a community project. Start with\n[CONTRIBUTING.md](CONTRIBUTING.md), browse\n[good first issues](docs/good-first-issues.md), and see the\n[roadmap](ROADMAP.md) for where it's heading. The architecture and a worked\n\"add a tool\" example are in [docs/extending.md](docs/extending.md).\n\n## License\nApache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 11928,
  "sha": "6da3ae3a50179be9b8634a5cfb507058433c855298460ba3aff28bc9716e81d5",
  "repo_slug": "simontarara62/capitalcom-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_simontarara62_capitalcom_mcp_s_e2dafc80/readme"
}