# ariadng/metatrader-mcp-server architecture

> Architecture diagram of the GitHub repository ariadng/metatrader-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ariadng/metatrader-mcp-server
- Repository: https://github.com/ariadng/metatrader-mcp-server

## Overview

MetaTrader Client is the shared Python interface to a local MetaTrader 5 terminal, exposing account, market, order, and history operations. The principal workflow is an AI assistant calling MCP tools, which obtain a connected client and invoke those operations; the repository also offers REST and WebSocket quote interfaces. Connection management underpins client operations. REST router-to-client calls are not established by the sampled evidence, so those links are omitted; the REST route registration structure is documented by the source index.

Main entry points: [`src/metatrader_client/client.py`](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client.py) (Unified client), [`src/metatrader_client/client_market.py`](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_market.py) (Market data), [`src/metatrader_mcp/server.py`](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/server.py) (MCP tools), [`src/metatrader_mcp/utils.py`](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/utils.py) (MCP client setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_mcp_server["MCP tools<br/>[server.py]"]
  node_mcp_utils["MCP client setup<br/>[utils.py]"]
  node_rest_app["REST application<br/>[main.py]"]
  node_rest_routes["REST routers"]
  node_quote_server["Quote stream<br/>[server.py]"]
end

subgraph group_client["Trading Client"]
  node_mt5_client["Unified client<br/>[client.py]"]
end

subgraph group_connection["Terminal Connection"]
  node_connection_facade["Connection manager"]
end

subgraph group_domains["Trading Domains"]
  node_account["Account operations<br/>[client_account.py]"]
  node_market["Market data<br/>[client_market.py]"]
  node_orders["Order management<br/>[client_order.py]"]
  node_history["Trade history<br/>[client_history.py]"]
  node_account_info["Account details"]
  node_symbols["Symbol discovery<br/>[get_symbols.py]"]
  node_order_send["Order execution<br/>[send_order.py]"]
  node_return_codes["Trade result codes"]
end

node_assistant(("AI assistant"))
node_rest_user(("API consumer"))
node_quote_user(("Quote consumer"))
node_mt5_terminal["MetaTrader 5"]

node_assistant -->|"calls tools"| node_mcp_server
node_mcp_server -->|"gets client"| node_mcp_utils
node_mcp_utils -->|"creates client"| node_mt5_client
node_rest_user -->|"sends requests"| node_rest_app
node_rest_app -->|"registers routers"| node_rest_routes
node_quote_user -->|"opens stream"| node_quote_server
node_quote_server -->|"fetches quotes"| node_market
node_mt5_client -->|"delegates connection"| node_connection_facade
node_mt5_client -->|"creates account API"| node_account
node_mt5_client -->|"creates market API"| node_market
node_mt5_client -->|"creates order API"| node_orders
node_mt5_client -->|"creates history API"| node_history
node_connection_facade -->|"connects terminal"| node_mt5_terminal
node_account -->|"delegates details"| node_account_info
node_market -->|"delegates lookup"| node_symbols
node_orders -->|"submits orders"| node_order_send
node_order_send -->|"uses result codes"| node_return_codes

click node_mcp_server "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/server.py"
click node_mcp_utils "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/utils.py"
click node_rest_app "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_openapi/main.py"
click node_rest_routes "https://github.com/ariadng/metatrader-mcp-server/tree/main/src/metatrader_openapi/routers"
click node_quote_server "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_quote/server.py"
click node_mt5_client "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client.py"
click node_connection_facade "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_connection.py"
click node_account "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_account.py"
click node_market "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_market.py"
click node_orders "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_order.py"
click node_history "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_history.py"
click node_account_info "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/account/get_account_info.py"
click node_symbols "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/market/get_symbols.py"
click node_order_send "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/order/send_order.py"
click node_return_codes "https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/types/trade_return_codes.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_mcp_utils,node_rest_app,node_rest_routes,node_quote_server toneBlue
class node_mt5_client toneAmber
class node_connection_facade,node_rest_user toneMint
class node_account,node_market,node_orders,node_history,node_account_info,node_symbols,node_order_send,node_return_codes toneRose
class node_assistant,node_quote_user,node_mt5_terminal toneIndigo
```

## Components

### User Interfaces

- [MCP tools](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/server.py): `src/metatrader_mcp/server.py`
- [MCP client setup](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_mcp/utils.py): `src/metatrader_mcp/utils.py`
- [REST application](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_openapi/main.py): `src/metatrader_openapi/main.py`
- [REST routers](https://github.com/ariadng/metatrader-mcp-server/tree/main/src/metatrader_openapi/routers): `src/metatrader_openapi/routers`
- [Quote stream](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_quote/server.py): `src/metatrader_quote/server.py`

### Trading Client

- [Unified client](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client.py): `src/metatrader_client/client.py`

### Terminal Connection

- [Connection manager](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_connection.py): `src/metatrader_client/client_connection.py`

### Trading Domains

- [Account operations](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_account.py): `src/metatrader_client/client_account.py`
- [Market data](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_market.py): `src/metatrader_client/client_market.py`
- [Order management](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_order.py): `src/metatrader_client/client_order.py`
- [Trade history](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/client_history.py): `src/metatrader_client/client_history.py`
- [Account details](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/account/get_account_info.py): `src/metatrader_client/account/get_account_info.py`
- [Symbol discovery](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/market/get_symbols.py): `src/metatrader_client/market/get_symbols.py`
- [Order execution](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/order/send_order.py): `src/metatrader_client/order/send_order.py`
- [Trade result codes](https://github.com/ariadng/metatrader-mcp-server/blob/main/src/metatrader_client/types/trade_return_codes.py): `src/metatrader_client/types/trade_return_codes.py`

### Other components

- **AI assistant**
- **API consumer**
- **Quote consumer**
- **MetaTrader 5**

## Connections

- AI assistant → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → MCP client setup: gets client (evidence: `src/metatrader_mcp/server.py`)
- MCP client setup → Unified client: creates client (evidence: `src/metatrader_mcp/utils.py`)
- API consumer → REST application: sends requests (evidence: `README.md`)
- REST application → REST routers: registers routers (evidence: `src/metatrader_openapi/routers/__init__.py`)
- Quote consumer → Quote stream: opens stream (evidence: `README.md`)
- Quote stream → Market data: fetches quotes (evidence: `src/metatrader_quote/server.py`)
- Unified client → Connection manager: delegates connection (evidence: `src/metatrader_client/client.py`)
- Unified client → Account operations: creates account API (evidence: `src/metatrader_client/client.py`)
- Unified client → Market data: creates market API (evidence: `src/metatrader_client/client.py`)
- Unified client → Order management: creates order API (evidence: `src/metatrader_client/client.py`)
- Unified client → Trade history: creates history API (evidence: `src/metatrader_client/client.py`)
- Connection manager → MetaTrader 5: connects terminal (evidence: `src/metatrader_client/client_connection.py`)
- Account operations → Account details: delegates details (evidence: `src/metatrader_client/client_account.py`)
- Market data → Symbol discovery: delegates lookup (evidence: `src/metatrader_client/client_market.py`)
- Order management → Order execution: submits orders (evidence: `src/metatrader_client/client_order.py`)
- Order execution → Trade result codes: uses result codes