How to set up the Capital.com MCP Server

The Capital.com MCP Server lets you connect an AI assistant – such as Claude Code, Codex, Claude Desktop, Cursor, or Windsurf – to your trading account. Once set up, you can use natural language to analyse markets, check account information, review open positions and working orders, and preview and place trades from your AI assistant.

This guide walks you through each step, from creating your API credentials and installing the server, to connecting your chosen AI assistant and reviewing and confirming each trade before execution. You don’t need to be a developer, but you should feel comfortable following technical instructions. We recommend starting in demo mode before switching to a live account.

What is the Capital.com MCP Server?

The Capital.com MCP (Model Context Protocol) Server is a free, open-source tool that lets you connect an AI assistant to your trading account using your Capital.com API credentials and two-factor authentication (2FA). It acts as a bridge between your account and the AI, so the assistant can access market and account data and respond to your instructions in real time.

Once connected, your AI assistant can:

• Search available markets (such as forex, shares, commodities, and indices).
• Show your open positions, working orders, and account information.
• Pull historical prices and client sentiment data.
• Preview and execute trades, with explicit confirmation required before execution.

You remain fully responsible for any trading decisions made using the MCP Server. Always review trade previews carefully before confirming.

Which AI assistants can I use?

This guide covers setup for Claude Code, Codex, Claude Desktop, Cursor and Windsurf.

If you are unsure where to start, Claude Code may be a practical option if you are comfortable using Terminal. Claude Desktop may suit you better if you would prefer to edit a configuration file.

Step 1. Create your API credentials

First, generate API credentials inside your Capital.com account. This may take around two minutes.

1. Log in to your Capital.com account.
2. Enable two-factor authentication (2FA).
3. Go to Settings → API Integrations → Generate New Key.
4. Give your key a label, for example: MCP Server.
5. Create a custom API password. This is separate from your usual Capital.com login password.
6. Enter your 2FA code and generate the key.
7. Copy the API key immediately. It won’t be shown again.

You will need the following values in the next steps:

*Practise on a demo account before live trading.

Important: these credentials provide access to your trading account. Keep them private. Don’t share them or paste them into chat interfaces, and don’t store them in public documents. Anyone with access to these details may be able to access your account via the API.

Step 2. Install the Capital.com MCP Server

This is a one-time installation. You have two options – option A is recommended for most users.

Option A. One-click install (recommended)

The MCP Server includes a bundle file that lets Claude Desktop handle the installation for you – no terminal or config file editing required.

Before you begin: make sure uv is installed (for example, via brew install uv on Mac) and that you have Node.js installed for the pack command.

1. In your terminal, clone the repository and build the bundle:

git clone https://github.com/capital-com-sv/capital-mcp

cd capital-mcp

npx @anthropic-ai/mcpb pack . capital-mcp.mcpb

2. Open capital-mcp.mcpb by double-clicking it, or drag it into Claude Desktop.
3. Claude Desktop will prompt you for your API credentials. Enter them, then click ‘Install’.
4. Restart Claude Desktop and verify the connection by asking: 'What Capital.com tools are available?'

Option B. Manual install

Use this if you prefer not to use the bundle, or if you are connecting to Codex, Cursor, or Windsurf.

Terminal (Mac)

1. Download the server files

cd ~/Desktop

git clone https://github.com/capital-com-sv/capital-mcp

cd capital-mcp

2. Create an isolated Python environment and install dependencies

python3 -m venv venv

source venv/bin/activate

pip install -e ".[dev]"

3. Find your Python path

You’ll need this in the next step:

which python

This should return a file path similar to:

/Users/you/Desktop/capital-mcp/venv/bin/python

Copy and save this path. You’ll paste it into your AI assistant settings in Step 3.

Tip: On Mac, you can drag a file from Finder into the Terminal window to display its full path.

4. Check the server starts correctly

python -m capital_mcp.server

If no errors appear, the installation is complete. If you see an error, resolve it now – error messages are usually easier to diagnose at this stage than inside an AI assistant interface..

Command Prompt (Windows)

1. Download the server files

cd %USERPROFILE%\Desktop

git clone  https://gitlab.itcapital.io/integrations/capital.com-public-api-mcp.git

cd capital.com-public-api-mcp

This downloads the repository to your Desktop and opens the project folder.

2. Create a virtual environment and install dependencies

py -m venv venv

venv\Scripts\activate.bat

pip install -e ".[dev]"

This creates a virtual environment to keep the project’s dependencies separate from the rest of your system. Activating it makes sure the packages are installed in that environment.

3. Find your Python path

You’ll need this in the next step:

where python

You should see something like:

C:\Users\you\Desktop\capital.com-public-api-mcp\venv\Scripts\python.exe

Copy and save this path. You’ll paste it into your AI assistant settings in Step 3.

4. Check the server starts correctly

python -m capital_mcp.server

If no errors appear, the installation is complete. If you see an error, resolve it now before continuing.

Step 3. Connect your AI assistant

All three AI assistants need the same core information. Collect the following before you begin:

Claude Code setup 

In your terminal, run:

claude mcp add capital-com -- /path/to/capital-mcp/venv/bin/python -m capital_mcp.server

Replace /path/to/capital-mcp/venv/bin/python with the Python path you copied in Step 2.

To confirm the connection, ask Claude: 'What Capital.com tools are available?' You should see 36 tools listed.

Codex setup 

Go to Codex → Settings → MCP Servers → Add Server and complete the fields below.

Command

Paste your venv Python path, for example:

/Users/you/Desktop/capital.com-public-api-mcp/venv/bin/python

Arguments

Add these as two separate entries – do not combine them:

1. -m
2. capital_mcp.server

Environment variables

Add each variable individually:

Working directory

Set the working directory to ~/code.

Save your settings and restart Codex.

Type /mcp in the chat – you should see capital-com listed.

To confirm the connection, send these three messages:

Check my Capital.com session status

Login to my Capital.com account

List my accounts

If all three return valid responses, the server is connected correctly.

Claude Desktop setup

Terminal (Mac)

Open Terminal and run the following commands to create the configuration file:

mkdir -p ~/Library/Application\ Support/Claude

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Command Prompt (Windows)

Open Command Prompt (CMD) and run:

mkdir "%APPDATA%\Claude"

notepad "%APPDATA%\Claude\claude_desktop_config.json"

Terminal (Mac) and Command Prompt (Windows)

Paste the template below into the file and replace every ALL CAPS placeholder with your actual values:

{

  "mcpServers": {

    "capital-com": {

      "command": "/PASTE/YOUR/VENV/PYTHON/PATH",

      "args": ["-m", "capital_mcp.server"],

      "env": {

        "CAP_ENV": "demo",

        "CAP_API_KEY": "PASTE_API_KEY",

        "CAP_IDENTIFIER": "PASTE_YOUR_EMAIL",

        "CAP_API_PASSWORD": "PASTE_API_PASSWORD",

        "CAP_ALLOW_TRADING": "false",

        "CAP_ALLOWED_EPICS": ""

      }

    }

  }

}

Save the file: press Ctrl + O, then Enter, then Ctrl + X. Restart Claude Desktop.

To confirm the connection, ask Claude: ‘What Capital.com tools are available?’’

You should see 36 tools listed. If fewer tools appear, check the troubleshooting section below.

Cursor setup

Go to Settings → Extensions → MCP → Configure and add:

{

  "capital-com": {

    "command": "/path/to/venv/bin/python",

    "args": ["-m", "capital_mcp.server"],

    "env": {

      "CAP_ENV": "demo",

      "CAP_API_KEY": "your_api_key",

      "CAP_IDENTIFIER": "your_email",

      "CAP_API_PASSWORD": "your_password",

      "CAP_ALLOW_TRADING": "false"

    }

  }

}

Restart Cursor and test the connection with:

List my accounts

If the command returns your account information, the integration is working as expected.

Windsurf setup

Create or edit the file at ~/.windsurf/mcp/servers.json and add:

{

  "mcpServers": {

    "capital-com": {

      "command": "/path/to/capital-mcp/venv/bin/python",

      "args": ["-m", "capital_mcp.server"],

      "env": {

        "CAP_ENV": "demo",

        "CAP_API_KEY": "your_api_key_here",

        "CAP_IDENTIFIER": "your_email@example.com",

        "CAP_API_PASSWORD": "your_custom_password"

      }

    }

  }

}

Replace all placeholder values with your actual credentials from step 1.

Restart Windsurf and test the connection with: ‘List my accounts’.

How to trade with the MCP Server

Every trade placed through the MCP Server follows a mandatory three-step process. The server enforces this process and does not allow you to bypass it.

Step 1 – Preview your trade

Ask your AI assistant to preview a trade. It will return a proposal and a unique preview_id.

Example:

Preview buying 1.5 [instrument] with stop at 24.50

Step 2 –  Review the proposal

Read the details returned by the AI carefully before taking any further action. Check the instrument, size, direction, and risk parameters to ensure they match your intention.

If your requested size is below the broker minimum or above the broker maximum for that instrument, the server will return an error. Adjust the size and create a new preview.

Step 3 –  Confirm execution

If you want to proceed, send a second message to confirm:

Execute position with preview_id abc123 confirm=true

A trade cannot be placed without a valid preview_id from a completed preview. The server requires both steps before execution.

Each preview ID can only be used once. After a trade is confirmed and executed, the preview expires immediately. To place another trade, start a new preview.

Before switching to a live account

Confirm all of the following:

• All testing completed in demo mode (CAP_ENV = demo).
• CAP_ALLOW_TRADING kept as false throughout the setup.
• Session login, account listing, and market data all functioning correctly
• Full preview and execution flow successfully tested in demo account.
• You have consciously decided to switch CAP_ENV to live and CAP_ALLOW_TRADING to true.

To restrict which markets the server can trade, add a comma-separated list of instrument codes to CAP_ALLOWED_EPICS. Leave it empty to allow access to all available markets on your account.

Troubleshooting: common errors and fixes {#errors}