# Capital.com MCP Server

> Safe, guarded trading and market-data tools for the Capital.com Open API. Demo-first, allowlisted.

- **Type:** MCP server
- **Install:** `agentstack add mcp-simontarara62-capitalcom-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SimonTarara62](https://agentstack.voostack.com/s/simontarara62)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.3.1
- **License:** Apache-2.0
- **Upstream author:** [SimonTarara62](https://github.com/SimonTarara62)
- **Source:** https://github.com/SimonTarara62/capitalcom-mcp-server
- **Website:** https://pypi.org/project/capitalcom-mcp/

## Install

```sh
agentstack add mcp-simontarara62-capitalcom-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Capital.com MCP Server

Self-hosted **Model Context Protocol (MCP)** server for the **Capital.com Open
API**, written in Python on [FastMCP](https://github.com/jlowin/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`](https://github.com/SimonTarara62/capitalcom-cli)
broker engine (SDK).

**Works with** Claude Desktop · Claude Code · Cursor · VS Code (Copilot) ·
Windsurf · ChatGPT — any MCP client.

[](https://pypi.org/project/capitalcom-mcp/)
[](https://pypi.org/project/capitalcom-mcp/)
[](https://github.com/SimonTarara62/capitalcom-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/?search=io.github.SimonTarara62/capitalcom-mcp-server)
[](https://glama.ai/mcp/servers/nmcob5apit)
[](https://pypi.org/project/capitalcom-mcp/)

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

```bash
uvx capitalcom-mcp --help        # smoke test
```

Or install a persistent command with pipx:

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

```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](CHANGELOG.md).

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

```bash
uvx capitalcom-mcp init
```

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

```bash
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": ""` 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):

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

### Claude Code
```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):

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

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

```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](#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:

```bash
CAP_ENV_FILE=/home/you/.config/capital-mcp/.env \
  capitalcom-mcp run --transport http --host 0.0.0.0 --port 8000
# endpoint: http://: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](docs/api-stability.md).

### 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
```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:

```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](CONTRIBUTING.md), browse
[good first issues](docs/good-first-issues.md), and see the
[roadmap](ROADMAP.md) for where it's heading. The architecture and a worked
"add a tool" example are in [docs/extending.md](docs/extending.md).

## License
Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SimonTarara62](https://github.com/SimonTarara62)
- **Source:** [SimonTarara62/capitalcom-mcp-server](https://github.com/SimonTarara62/capitalcom-mcp-server)
- **License:** Apache-2.0
- **Homepage:** https://pypi.org/project/capitalcom-mcp/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.3.1 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.3.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-simontarara62-capitalcom-mcp-server
- Seller: https://agentstack.voostack.com/s/simontarara62
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.