Connecting AI Agents to MetaTrader 5 with MCP: A Beginner's Guide

If you have ever pasted a screenshot of a chart into ChatGPT and asked it a question about your positions, you already know the shape of the problem: the model can reason about trading, but it cannot see your terminal. It has no idea what your balance is, what EURUSD is doing right now, or which orders are open. You are the integration layer, and you do it by hand, one clipboard at a time.

MCP, the Model Context Protocol, is the standard that closes that gap. It gives an AI assistant a defined way to call tools that programs expose, and it means you can connect an assistant to your MetaTrader 5 terminal without writing a plugin for every chat app you happen to use.

This guide is for retail forex and CFD traders who are comfortable installing software and editing a config file, but who do not write Python for a living. By the end you will have an AI assistant that can read your account, pull candles, list positions, and place orders on a demo account. That last word matters. Everything here is educational, and you should treat a live account as a much later step.

What MCP actually is

MCP is an open standard created by Anthropic that defines how AI models connect to external tools and data. It is a specification, not a product: a shared set of rules for describing a tool, calling it, and getting a result back.

If you have used the MetaTrader5 Python package, you already understand the idea. That package is a bridge between Python and the MT5 terminal, your script calls mt5.initialize() and suddenly Python can read prices and send orders. MCP is the same concept one level higher. Instead of bridging Python to MT5, it bridges any AI client to tools that a program exposes. The tool author writes the bridge once; every compatible assistant can then use it.

Why does that matter? Without a standard, every AI application would need its own plugin format. Claude Desktop, Cursor, VS Code Copilot, and Open WebUI would each require a separate custom integration, maintained separately, breaking separately. With MCP, you build one server and every compatible client can talk to it. The official documentation at modelcontextprotocol.io is worth twenty minutes of your time once you have things running.

Tools: the vocabulary that matters

An MCP server exposes tools. A tool is a named function with typed parameters and a description written for the model to read. When a client connects, it asks the server for the tool list and the schemas, then hands that list to the language model along with your question. The model picks a tool and fills in the arguments.

A concrete example. You type:

Show me the last 10 hourly candles for EURUSD.

The model reads the available tools, finds one called get_rates, and issues a structured call:

get_rates(symbol="EURUSD", timeframe="H1", count=10)

The server translates that into MetaTrader5 package calls, grabs the data from your terminal, and returns it. The model then writes the answer in prose, or, if you asked it to, a table. No custom parsing code on your side. That is the whole value proposition: the model reads the tool description and figures out the rest.

How the pieces fit together

The chain is short enough to draw in one line:

You → AI Assistant → MCP Server → MetaTrader 5 → Your Trades

You ask a question in plain English. The assistant decides which tool to call. The MCP server receives the call and uses the MetaTrader5 Python package to talk to the terminal. The terminal does the actual work. The result travels back up the chain.

Why the transport choice matters

MCP supports several transports, the mechanism the client and server use to exchange messages. For a server sitting on your own machine and controlling a trading terminal, the standard choice is stdio: standard input and output.

With stdio there is no HTTP server, no port to configure, and nothing exposed on the network. The client starts the server process when it needs it and the two talk over pipes. When the client closes, the server goes away. For something that can place trades, this is both the simplest and the most defensible option, there is no port for anything else on your network to find.

HTTP transport exists too, and it is genuinely useful while developing or testing a server you are building yourself. But for plugging an off-the-shelf MT5 server into a desktop assistant, stdio is the default and you should leave it alone.

What you need before you start

The prerequisite list is short, but one item on it is non-negotiable.

• Windows. The MetaTrader5 Python package talks to the terminal through a COM interface. It is Windows-only. This is a hard constraint, not a preference, and it is the single most common reason a Linux or macOS user cannot follow this guide. WSL does not fix it. The official package documentation at mql5.com states the platform support plainly.
• MetaTrader 5 installed and logged in on that Windows machine.
• Python 3.10 or newer, 3.11 or newer for one of the two servers below.
• An MT5 account. Use a demo account. Everything in this article works identically on demo, and the failure modes are much cheaper there.
• An MCP-capable client. Claude Desktop is the most thoroughly documented for these servers; other clients support MCP too, with varying degrees of hand-holding.

If you are on a Mac or Linux box and want to experiment anyway, understand that you are limited to reading third-party data, the terminal link requires Windows.

Option A: the quick install

The first off-the-shelf option is metatrader-mcp-server, published on PyPI by ariadng under the MIT licence. It requires Python 3.10 or newer and is the more flexible of the two, because it can run as an MCP server, as a REST API, or as a WebSocket stream. It is documented for use with Claude Desktop and, via Open WebUI, with ChatGPT.

Install it:

pip install metatrader-mcp-server

Your credentials stay on your machine, the server runs locally and talks to the terminal locally. If you only need the MCP server and nothing else, this is the shorter path and the one to try first.

Option B: the uvx route

The second option is mcp-metatrader5-server, published by Qoyyuum, also MIT-licensed. It requires Python 3.11 or newer and MetaTrader 5 running on Windows. It runs stdio by default, which is exactly what you want.

The quickest way to try it, without installing anything permanently, is uvx:

uvx --from mcp-metatrader5-server mt5mcp

To wire it into Claude Desktop, add an entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-metatrader5-server": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Qoyyuum/mcp-metatrader5-server", "mt5mcp"]
    }
  }
}

If you would rather install it properly from a cloned checkout, the repository also supports:

uv run fastmcp install claude-desktop src/mcp_mt5/main.py

Either way, restart the client afterwards. MCP servers are launched at client startup, so a running assistant will not notice a config change until you close and reopen it.

What the servers can actually do

Across these two projects, the operations cover the practical core of terminal work:

• Read account balance, equity, and margin.
• List available symbols.
• Fetch real-time prices.
• Pull historical OHLCV candles.
• Place, modify, and close orders.
• List open positions and close them.
• Read trade history.

Read that list twice, because the second half is where the risk lives. The same interface that lets you ask for candles will happily place an order.

The step everyone misses

Before any of this works, you have to enable algorithmic trading in the terminal.

In MetaTrader 5, go to Tools → Options → Expert Advisors and tick Allow algorithmic trading. Confirm and restart the terminal if it asks.

Skip this and you get the most confusing failure mode in the whole setup: the server connects, the tools list loads, prices and candles come back perfectly, and every single order is rejected. Nothing in the error message points at the checkbox. People spend an hour debugging Python when the answer is a dialog box in the terminal.

While you are in there, check the toolbar too. There is a separate Algo Trading button on the main toolbar that toggles the same permission, and it is easy to leave it off by accident.

Testing on a demo account first

With the server connected and algorithmic trading enabled, start with read-only prompts. They prove the plumbing works without risking anything.

1. What is my account balance and equity?, verifies the connection and the account tools.
2. List the symbols I can trade., confirms symbol discovery is working.
3. What is the current bid and ask for EURUSD?, checks live price retrieval.
4. Show me the last 20 H1 candles for EURUSD., exercises the historical data path.
5. What positions do I have open?, should return an empty list, which is itself a valid answer.

Once those five behave, try a single small order on the demo account:

Buy 0.01 lots of EURUSD on the demo account with a 20 pip stop loss.

Then check the terminal yourself. Do not take the assistant's word for it. Ask it to list open positions, and compare against the Trade tab in MT5. If those two agree, your setup is genuinely working, and you have learned the most important habit in this whole workflow: verify in the terminal, not in the chat.

What could go wrong

The honest limitations matter more than the setup steps, because they determine whether this belongs anywhere near your money.

• Your machine must be on. Everything runs locally on Windows. This is not a cloud service. MT5 has to be running and logged in. Close the laptop lid, sleep the machine, or let the terminal disconnect and the assistant goes blind.
• The AI is a language front end, not a strategy. It does not decide when to trade unless you tell it to. Nothing here generates edge. Garbage prompts produce garbage trades, faster and with less friction than you could manage by hand.
• Ambiguous instructions get ambiguous results. Say "close my EURUSD position" while holding three of them and you may not get the one you meant. The model resolves ambiguity the way a language model does, plausibly, not necessarily correctly.
• There is no built-in risk limit. Nothing in the protocol or the servers stops an oversized order. There is no lot-size ceiling, no daily loss cap, no confirm prompt you did not ask for. If you would not type the order yourself, do not let the model type it either.
• These are community projects. Both servers are third-party, MIT-licensed work. They are not official MetaQuotes or Anthropic products, and nobody is on the hook if one misbehaves. Read the code before you point it at anything with real money in it.
• Latency is dominated by the model. The tool call itself round-trips in milliseconds. The language model's own inference time, often one to five seconds, is the real delay. This is not suitable for latency-sensitive scalping, and no amount of tuning changes that. It is a text interface to a trading terminal, not an execution engine.

A practical rule that covers most of the list: run on demo until you are bored of it, then start live with position sizes small enough that a mistake is an annoyance rather than a story.

Where to go next

Running someone else's server is the sensible way to start, but it is also a ceiling. The tools available are the tools the author decided to expose, if you want your own custom indicator, a specific risk check that refuses any order above a fixed size, or a tool that reads your own database of setups, you need to build the server yourself.

That turns out to be less work than you would expect. FastMCP makes an MCP server a matter of decorating Python functions, and the MetaTrader5 package is the same one you may already be using in scripts. The advanced follow-up to this guide walks through building a server that exposes your tools with your guardrails, including the risk limit that is conspicuously missing from the off-the-shelf options.

Until then, get the demo connection working. Verify every trade in the terminal. And read the tool list carefully before you let anything near an account you care about.