MetaTrader 5 MCP Bridge

MetaTrader 5 MCP ブリッジ

設定可能な人間の承認ゲートを備え、Model Context Protocol を介して AI エージェントが MetaTrader 5 アカウントを管理できるようにします。

_{Hermes エージェントが、Linux 上で MCP を介して一貫して、デモアカウントで実際の 0.01 ロットの取引を開始してから決済する様子です。}

_{モックアップではありません。MetaTrader 5 の「履歴」タブに表示された同じ往復取引で、チケット番号と残高は録画内容と一致しています。}

⚠️ このソフトウェアは、MetaTrader 5 ターミナルを通じて、実際の注文と取り消せない約定を伴う 実際の 取引を行います。 ライブアカウントに接続する前に、 DISCLAIMER.md と SECURITY.md をお読みください。必ず、まずデモアカウントでテストしてください。

ローカルで実行されます。クラウドもテレメトリーもなく、エージェントと同じプロセスツリー内で動作します。 Windows（ネイティブ）または Linux（Docker 経由）に対応し、Python 3.10 以降が必要です。

📖 このプロジェクトの背景： このプロジェクトは、Fintrix エンジニアリングブログの「Trade with AI agent」シリーズ第 1 回、 Wiring AI agent into MetaTrader 5 に沿って、手順を追って構築されています。

概要

mt5-mcp を使うと、AI エージェントは Model Context Protocol を介して MetaTrader 5 アカウントの情報を読み取り、取引を行えます。

• 読み取り専用ツール 12 個：口座、レート、ポジション、注文、履歴、OHLC バー、ブローカーが算出する証拠金見積もり、ネイティブのチャートスクリーンショット（Windows）。承認ゲートはありません。
• 変更を伴うツール 4 個：place_order、modify_order、cancel_order、 close_position。それぞれに、事前チェック、人間による承認、冪等性、監査の各レイヤーが適用されます。
• 購読可能なリソース 3 個：変更通知をプッシュする、最新の account://、positions://、quotes://{symbol} スナップショットです。
• すぐに使える Claude Code スキル 2 個を .claude/skills/ に同梱しています。mt5-market-data と mt5-trading は、エージェントに口座情報の読み取り方法と承認フローの安全な実行方法を教えます。

ツールの全一覧と承認フローについては、docs/tools.md をご覧ください。

mt5-mcp を選ぶ理由

• 単なる API ラッパーではなく、安全レイヤーです。 変更を伴うすべての呼び出しは、事前チェック -> オプトイン方式の人間の同意ゲート（承認を必須にするには有効化します） -> 冪等性の確保 -> 追記専用の監査ログを経由するため、取引に人間を介在させ、エージェントが行った操作を常に再現可能な記録として残せます。
• 脅威モデルを偽りなく示します。 place_order に接続された LLM を実際の攻撃対象領域として扱い、その点を明言しています。MCP 自体は明確に セキュリティ境界ではありません（SECURITY.md を参照）。
• モックアップではなく、検証可能な証拠です。 上記のデモは実際の往復処理です。チケットと残高は、MetaTrader 5 の「履歴」タブの内容と一致します。
• ローカル優先です。 クラウドもテレメトリもなく、エージェントのそばで動作します。Windows ネイティブ、またはオールインワン Docker イメージを使った Linux で利用できます（rpyc のバージョンを合わせる必要はありません）。

クイックスタート（Windows、ネイティブ）

pip install mt5-trading-mcp

1. MetaTrader 5 を起動し、ブローカーにログインします。AlgoTrading を有効にします（ツールバーのボタンが緑色になります）。
2. ターミナルに接続できることを確認します：python -m mt5_mcp doctor：[INFO] backend: native と [PASS] の行が表示されます。
3. 実行します：python -m mt5_mcp serve。

1 つのコマンドで OpenClaw に接続します（mcp.servers エントリを登録します）：

openclaw mcp set mt5-mcp '{"command":"python","args":["-m","mt5_mcp","serve"]}'

クイックスタート（Linux、Docker）

MT5 ターミナルと MCP は、オールインワンイメージ内でヘッドレス動作し、エージェントは HTTP 経由で MCP と通信します。ホスト側の Python もブリッジも不要です。

cp deploy/.env.example deploy/.env   # add MT5_LOGIN / MT5_PASSWORD / MT5_SERVER
docker compose -f deploy/docker-compose.yml up -d

まず、KasmVNC の Web UI でターミナルにログインします（http://127.0.0.1:3001 の File -> Login to Trade Account。再起動後もログイン状態は保持されます）。次に、エージェントの接続先を http://127.0.0.1:8765/mcp に設定します。1 つのコマンドで OpenClaw に接続します：

openclaw mcp set mt5-mcp '{"url":"http://127.0.0.1:8765/mcp","transport":"streamable-http"}'

詳しい手順： docs/installation.md。

チャートのスクリーンショット（Windows のみ）

get_chart_screenshot(symbol, timeframe, annotations?) は、ネイティブ MT5 チャートの PNG を返します。必要に応じて注釈を付けられるため、LLM はローソク足、サポート／レジスタンス、パターンなどを視覚的に読み取れます。MetaTrader5 Python API ではチャートをキャプチャできないため、GUI ターミナル内で動作し、ChartScreenShot() を呼び出す小さな MQL5 エキスパートアドバイザーを使用します。

キャプチャ前にサポート／レジスタンスライン、トレンドライン、メモを描画する方法については、チャートへの注釈を参照してください。

セットアップ（初回のみ）：

1. AgentScreenshot EA をインストールしてチャートに設定します。詳しくは mql5/README.md を参照してください。
2. 必要に応じてテンプレートを設定し、インジケーターや描画内容がスクリーンショットに表示されるようにします。設定の [screenshot] セクションに [screenshot] template = "agent.tpl" を指定するか、デフォルトのチャートを使う場合は未設定のままにします。

設定項目（[screenshot] セクション）：width（デフォルト 1600）、height（デフォルト 900）、template（デフォルトは未設定）、timeout_s（デフォルト 10）。

ヘッドレスの Linux／Docker デプロイでは利用できません。GUI ターミナルが必要です。Windows 以外では、このツールは SCREENSHOT_NOT_SUPPORTED を返します。

AI エージェント向け

このリポジトリをインストールして実行するように渡された場合は、docs/agents.md の手順書に従ってください。 プラットフォームの検出、インストール、検証、サーバーの登録、取引に関する厳格な安全ルールを説明しています。変更を伴うツールを呼び出す前に、必ずお読みください。

ドキュメント

ガイド	内容
インストールとセットアップ	必要条件、Windows + Linux/Docker のセットアップ、エージェントへの接続方法。
AI エージェント向け	サーバーをインストールして実行するエージェント向けの、ステップごとの手順書。
設定	config.toml のスキーマ、保存パス、ホットリロード。
ツールとリソース	読み取りツール、変更を伴うツールと同意フロー、サブスクライブ可能なリソース。
MCP クライアントのセットアップ	クライアントごとの設定スニペットと Claude Code の使用方法。
トランスポートとデプロイ	stdio/HTTP トランスポートと Windows VPS の構成例。
コントリビューション	貢献方法とテストの実行方法。
変更履歴	リリース履歴と既知の制限事項。

安全性

mt5-mcp はセキュリティ境界ではありません。厳格な制限（証拠金、最大ロット、銘柄の権限）はブローカーの MT5 サーバーが適用します。ポリシーエンジンの事前チェックは、エージェントのミスを早期に検出するための UX 上のガードレールであり、セキュリティ対策ではありません。

人間による同意ゲートはオプトインで、デフォルトでは無効です。auto_approve_notional のデフォルト値は 0 のため、変更を伴う呼び出しは自動実行されます（完全自動）。これは、信頼できるエージェントや無人エージェントを想定しています。auto_approve_notional を 0 より大きい値に設定してゲートを有効にしてください。その値以上の想定元本を持つ注文／決済は ApprovalPreview を返し、確認が必要になります。また、ストップを広げる、または削除する変更にも承認が必要です。事前チェックの上限（max_*）と銘柄の許可／拒否リストも同様にオプトインです（0／空 = 無効）。変更を伴うすべての呼び出しは、いずれの場合も追記専用の監査 JSONL ログに記録されます。脆弱性の報告については、SECURITY.md をご覧ください。

アーキテクチャ

mt5-mcp は、MetaTrader 5 Python ライブラリを FastMCP サーバーの背後でラップします。単一の MT5Client（src/mt5_mcp/adapter/）が、ターミナル接続、ブローカーのタイムゾーン推定、型変換を担い、それ以外のすべてはその上に構築されます。src/mt5_mcp/types.py / src/mt5_mcp/config.py の Pydantic モデルが、データと設定のスキーマの信頼できる情報源です。

     Agent / MCP client  (Hermes, OpenClaw, Claude Code, Claude Desktop, …)
                               │
                               │   stdio  ·  loopback HTTP
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                      FastMCP server                      │
 │                                                          │
 │   tools/        resources/        policy/                │
 │   read +        subscribable      consent · idempotency  │
 │   mutating      account/quotes    · audit (JSONL)        │
 │                                                          │
 │   streaming/  - change-detection poller + dispatcher     │
 │   types.py · config.py - Pydantic schemas: source of     │
 │                          truth for data + config         │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                                                          │
 │   adapter/  MT5Client                                    │
 │   one terminal connection · broker-TZ inference ·        │
 │   type conversions · transparent reinit                  │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
MetaTrader 5 Python library  ->  broker terminal  ->  broker server

表示されているモジュールパス（tools/、resources/、policy/、streaming/、adapter/、types.py、config.py）は、すべて src/mt5_mcp/ 配下にあります。

コントリビューション

貢献を歓迎します。開発環境のセットアップ、テストのワークフロー、プロジェクトの原則については、 CONTRIBUTING.md をご覧ください。

ライセンス

MIT - LICENSE をご覧ください。