ariadng/metatrader-mcp-server

이것은 무엇인가요?
특징 (Features)
누구를 위한 것인가요?
중요한 면책 조항 (Important Disclaimer)
사전 요구 사항 (Prerequisites)
빠른 시작 (Quick Start)
트레이딩 어시스턴트 기술 (Trading Assistant Skill)
사용 예시 (Usage Examples)
사용 가능한 작업 (Available Operations)
WebSocket 시세 서버 (WebSocket Quote Server)
고급 설정 (Advanced Configuration)
로드맵 (Roadmap)
개발 (Development)
기여하기 (Contributing)
문서 (Documentation)
도움받기 (Getting Help)
라이선스 (License)

MetaTrader MCP Server는 AI 어시스턴트(Claude, ChatGPT 등)를 MetaTrader 5 트레이딩 플랫폼에 연결하는 브리지 (Bridge)입니다. 버튼을 클릭하는 대신, AI 어시스턴트에게 무엇을 할지 간단히 말하기만 하면 됩니다:

"내 계좌 잔고를 보여줘" "EUR/USD 0.01 로트 매수해줘" "수익 중인 모든 포지션을 종료해줘"

AI는 사용자의 요청을 이해하고 MetaTrader 5에서 자동으로 실행합니다.

사용자 → AI 어시스턴트 → MCP 서버 → MetaTrader 5 → 사용자의 거래

🗣️ 자연어 트레이딩 (Natural Language Trading)- 평이한 영어로 AI와 대화하여 거래 실행
🤖 멀티 AI 지원 (Multi-AI Support)- Claude Desktop, ChatGPT (Open WebUI를 통해) 등과 연동 가능
📊 전체 시장 접근 (Full Market Access)- 실시간 가격, 과거 데이터 및 심볼 (Symbol) 정보 획득
💼 완전한 계좌 제어 (Complete Account Control)- 잔고, 자산 (Equity), 증거금 (Margin) 및 트레이딩 통계 확인
⚡ 주문 관리 (Order Management)- 간단한 명령으로 주문 생성, 수정 및 종료
🔒 보안 (Secure)- 모든 인증 정보는 사용자의 로컬 머신에 유지
🌐 유연한 인터페이스 (Flexible Interfaces)- MCP 서버, REST API 또는 WebSocket 스트림으로 사용 가능
📖 잘 정리된 문서 (Well Documented)- 포괄적인 가이드 및 예시 제공

트레이더 (Traders): AI를 사용하여 트레이딩을 자동화하고자 하는 분
개발자 (Developers): 트레이딩 봇 또는 분석 도구를 구축하는 분
분석가 (Analysts): 시장 데이터에 빠르게 접근해야 하는 분
기타 (Anyone): AI와 금융 시장의 결합에 관심이 있는 모든 분

다음 내용을 주의 깊게 읽어주십시오:

금융 상품을 거래하는 것은 상당한 손실 위험을 수반합니다. 이 소프트웨어는 있는 그대로(as-is) 제공되며, 개발자는 이 소프트웨어의 사용으로 인한 어떠한 거래 손실, 이익 또는 결과에 대해서도 책임을 지지 않습니다.

이 소프트웨어를 사용함으로써 귀하는 다음 사항을 인정하게 됩니다:

귀하는 금융 거래 (Financial trading)의 위험을 이해합니다.
귀하는 이 시스템을 통해 실행되는 모든 거래에 대한 책임을 집니다.
귀하는 어떠한 결과에 대해서도 개발자에게 책임을 묻지 않습니다.
귀하는 본 소프트웨어를 본인의 위험 부담 하에 사용합니다.

이것은 금융 조언이 아닙니다. 항상 책임감 있게 거래하십시오.

시작하기 전에 다음 사항을 준비했는지 확인하십시오:

Python 3.10 이상 - [여기에서 다운로드]
MetaTrader 5 터미널 - [여기에서 다운로드]
MT5 거래 계좌 - 데모 또는 실계좌 자격 증명

로그인 번호
비밀번호
서버 이름 (예: "MetaQuotes-Demo")

터미널 또는 명령 프롬프트를 열고 다음을 실행하십시오:

pip install metatrader-mcp-server

MetaTrader 5를 엽니다.
다음 경로로 이동합니다:
Tools (도구)

→ Options (옵션)

Expert Advisors (전문가 어드바이저) 탭을 클릭합니다.
Allow algorithmic trading (알고리즘 트레이딩 허용) 확인란을 체크합니다.
OK를 클릭합니다.

사용 방식에 따라 하나를 선택하십시오:

Claude Desktop 설정 파일을 찾습니다:

Windows: %APPDATA%\Claude\claude_desktop_config.json

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

파일을 열고 다음 구성을 추가합니다:

{
"mcpServers": {
"metatrader": {
...

선택 사항: 사용자 정의 MT5 터미널 경로 지정

MT5 터미널이 표준 위치가 아닌 곳에 설치된 경우, --path 인자를 추가하십시오:

{
"mcpServers": {
"metatrader": {
...

YOUR_MT5_LOGIN, YOUR_MT5_PASSWORD, YOUR_MT5_SERVER를 실제 자격 증명으로 교체합니다.
Claude Desktop을 재시작합니다.
대화를 시작하십시오! 다음을 시도해 보세요:

"내 계좌 잔액은 얼마인가요?"

HTTP 서버를 시작합니다:

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 0.0.0.0 --port 8000

선택 사항: 사용자 정의 MT5 터미널 경로 지정

MT5 터미널이 표준 위치가 아닌 곳에 설치된 경우, --path 인자를 추가하십시오:

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --path "C:\Program Files\MetaTrader 5\terminal64.exe" --host 0.0.0.0 --port 8000

브라우저에서 http://localhost:8000/docs를 열어 API 문서를 확인합니다.
Open WebUI에서:
Settings (설정) → Tools (도구)로 이동합니다. - Add Tool Server (도구 서버 추가)를 클릭합니다. - http://localhost:8000을 입력합니다.
Save (저장)를 클릭합니다.
이동합니다.

이제 Open WebUI 채팅에서 트레이딩 도구들을 사용할 수 있습니다!

대시보드, 봇 또는 모니터링을 위해 WebSocket을 통해 실시간 틱 데이터(bid, ask, spread, volume)를 스트리밍하세요:

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

어떠한 WebSocket 클라이언트와도 연결할 수 있습니다:

websocat ws://localhost:8765

connected 메시지를 받은 후, JSON 형식의 연속적인 틱 업데이트를 받게 됩니다. 자세한 내용은 WebSocket Quote Server를 참조하세요.

Windows VPS(MT5가 설치된 곳)에서 MCP 서버를 실행하고, Claude Desktop 또는 Claude Code에서 원격으로 연결하세요.

Server-side (서버 측, Windows VPS 상에서):

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

이 명령은 기본적으로 0.0.0.0:8080에서 SSE 서버를 시작합니다. --host 및 --port를 사용하여 사용자 정의할 수 있습니다:

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 127.0.0.1 --port 9000

Client-side (클라이언트 측, 로컬 머신의 Claude Desktop 설정):

{
"mcpServers": {
"metatrader": {
...

VPS_IP를 서버의 IP 주소로 교체하세요.

보안 경고: MCP 프로토콜은 인증 (authentication)을 포함하지 않습니다. 네트워크를 통해 SSE 서버를 노출할 때는 방화벽을 사용하여 IP별로 액세스를 제한하거나, 인증 기능이 있는 리버스 프록시 (reverse proxy) 뒤에 배치하거나, SSH 터널을 사용하세요.

claude-skill/ 디렉토리에 사전 구축된 Trading Terminal Assistant (트레이딩 터미널 어시스턴트) 스킬이 포함되어 있습니다. 이 스킬은 Claude에게 32개의 모든 트레이딩 도구, 출력 포맷팅, 그리고 MetaTrader 5 도메인 전문 지식에 대한 구조화된 지식을 제공합니다.

Option 1: Symlink (심볼릭 링크, 권장 방식)

표준 Claude Code 스킬 디렉토리에서 claude-skill/로 향하는 심볼릭 링크를 생성합니다:

cd metatrader-mcp-server
mkdir -p .claude
ln -s ../claude-skill .claude/skills

해당 스킬은 자동으로 검색되며 /trading으로 사용할 수 있게 됩니다.

Option 2: Copy (복사)

스킬 파일을 Claude Code 스킬 디렉토리로 복사합니다:

cd metatrader-mcp-server
mkdir -p .claude/skills
cp -r claude-skill/trading .claude/skills/trading

Claude Desktop의 경우, 스킬을 글로벌 Claude 스킬 디렉토리로 복사합니다:

# macOS
mkdir -p ~/Library/Application\ Support/Claude/skills
cp -r claude-skill/trading ~/Library/Application\ Support/Claude/skills/trading
...

직접 실행 (Direct Execution): 요청 시 추가 확인 없이 즉시 거래를 실행합니다.
워크플로우 (Workflows): 복잡한 작업을 위해 도구들을 체이닝(chaining)하는 방법을 알고 있습니다 (예: 시장가 주문을 넣은 후 SL/TP 설정).
포맷팅 (Formatting): 계좌 데이터, 포지션, 주문 및 가격을 깔끔한 터미널 스타일의 테이블로 제시합니다.
도메인 지식 (Domain Knowledge): MT5 주문 유형, 타임프레임 (timeframes), 심볼 형식 및 체결 모드 (filling modes)를 이해합니다.

설치가 완료되면 /trading으로 호출하거나,

또는 다음과 같이 거래 관련 질문을 자연스럽게 던지세요:

/trading
> Show me my account dashboard
> Buy 0.1 lots of EURUSD with SL at 1.0800
...

WebSocket Quote Server는 MetaTrader 5에서 실시간 틱 (tick) 데이터를 모든 WebSocket 클라이언트로 스트리밍합니다. 이는 라이브 대시보드, 알고리즘 트레이딩 프론트엔드 및 실시간 모니터링에 이상적입니다.

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

서버는 기본적으로 ws://0.0.0.0:8765에서 시작됩니다.

metatrader-quote-server \
--login YOUR_LOGIN \
--password YOUR_PASSWORD \
...

플래그 (Flag)	환경 변수 (Env Var)	기본값 (Default)	설명
`--host`	`QUOTE_HOST`	`0.0.0.0`	바인딩할 호스트
`--port`	`QUOTE_PORT`	`8765`	바인딩할 포트
`--symbols`	`QUOTE_SYMBOLS`	`XAUUSD,USOIL,GBPUSD,USDJPY,EURUSD,BTCUSD`	스트리밍할 쉼표로 구분된 심볼
`--poll-interval`	`QUOTE_POLL_INTERVAL_MS`	`100`	밀리초 단위의 틱 폴링 (polling) 간격

CLI 플래그는 환경 변수보다 우선하며, 환경 변수는 기본값보다 우선합니다.

연결 시 (On connect) — 서버는 심볼 목록이 포함된 connected 메시지를 보내고, 이어서 캐시된 모든 틱을 전송합니다:

{"type": "connected", "symbols": ["XAUUSD", "EURUSD", "GBPUSD"], "poll_interval_ms": 100}

틱 업데이트 (Tick updates) — 매도 호가 (bid), 매수 호가 (ask), 또는 거래량 (volume)이 변경될 때마다 전송됩니다:

{"type": "tick", "symbol": "XAUUSD", "bid": 2345.67, "ask": 2345.89, "spread": 0.22, "volume": 1234, "time": "2026-03-14T10:30:45+00:00"}

오류 (Errors) — 심볼을 가져올 수 없는 경우 전송됩니다:

{"type": "error", "symbol": "INVALID", "message": "Symbol not found or data unavailable"}

import asyncio
import json
from websockets.asyncio.client import connect
...

변경 감지 (Change detection): 매도 호가 (bid), 매수 호가 (ask), 또는 거래량 (volume)이 실제로 변경될 때만 브로드캐스트하여 불필요한 트래픽을 줄입니다. 늦은 참여자 (Late joiners): 새로운 클라이언트는 연결 시 즉시 캐시된 틱을 수신하므로 다음 변경 사항을 기다릴 필요가 없습니다. MT5 스레드 안전성 (MT5 thread safety): 모든 MT5 SDK 호출은 동시 액세스 문제를 방지하기 위해 단일 스레드 실행기 (single-thread executor)를 통해 직렬화됩니다. 다중 클라이언트 (Multiple clients): 원하는 수만큼의 WebSocket 클라이언트가 동시에 연결될 수 있습니다.

설정이 완료되면 자연스럽게 대화할 수 있습니다:

계정 확인:

사용자: "내 계정 정보를 보여줘"

Claude:

잔고 (balance), 자산 (equity), 증거금 (margin), 레버리지 (leverage) 등을 반환합니다.

시장 데이터 가져오기:

사용자: "EUR/USD의 현재 가격은 뭐야?"

Claude:

매도 호가 (bid), 매수 호가 (ask), 스프레드 (spread)를 보여줍니다.

거래 실행:

사용자: "GBP/USD 0.01 로트 매수해줘. 손절매 (stop loss)는 1.2500, 익절 (take profit)은 1.2700으로 설정해줘"

Claude:

거래를 실행하고 확인해줍니다.

포지션 관리:

사용자: "내 모든 손실 포지션을 종료해줘"

Claude:

포지션을 종료하고 결과를 보고합니다.

내역 분석:

사용자: "지난주 EUR/USD 거래 내역을 모두 보여줘"

Claude:

거래 내역을 표 형태로 반환합니다.

# 계정 정보 가져오기
curl http://localhost:8000/api/v1/account/info
# 현재 가격 가져오기
...

from metatrader_client import MT5Client
# MT5에 연결
config = {
...

get_account_info

잔고 (balance), 자산 (equity), 수익 (profit), 증거금 수준 (margin level), 레버리지 (leverage), 통화 (currency) 가져오기

get_symbols

사용 가능한 모든 거래 심볼 (trading symbols) 목록 나열

get_symbol_price

심볼의 현재 매도/매수 가격 (bid/ask price) 가져오기

get_candles_latest

최근 가격 캔들 (OHLCV 데이터) 가져오기

get_candles_by_date

특정 날짜 범위의 과거 캔들 가져오기

get_symbol_info

상세 심볼 정보 가져오기

place_market_order

즉시 매수/매도 (BUY/SELL) 주문 실행

place_pending_order

향후 실행을 위한 지정가/스탑 주문 (limit/stop orders) 배치

modify_position

손절매 (stop loss) 또는 익절 (take profit) 업데이트

modify_pending_order

대기 주문 (pending order) 파라미터 수정

get_all_positions

모든 오픈 포지션 (open positions) 보기

get_positions_by_symbol

거래 쌍 (trading pair)별로 포지션 필터링

get_positions_by_id

특정 포지션 상세 정보 가져오기

close_position

특정 포지션 종료

close_all_positions

모든 오픈 포지션 종료

close_all_positions_by_symbol

특정 심볼에 대한 모든 포지션 종료

close_all_profitable_positions

수익 중인 거래만 종료

close_all_losing_positions

손실 중인 거래만 종료

get_all_pending_orders

모든 대기 주문 (pending orders) 목록 나열

get_pending_orders_by_symbol

심볼별로 대기 주문 필터링

cancel_pending_order

특정 대기 주문 취소

cancel_all_pending_orders

모든 대기 주문 취소

cancel_pending_orders_by_symbol

특정 심볼에 대한 대기 주문 취소

get_deals

과거 완료된 거래 (completed trades) 가져오기

get_orders

과거 주문 기록 가져오기

명령줄에 자격 증명 (credentials)을 직접 입력하는 대신, .env 파일을 생성하세요:

LOGIN=12345678
PASSWORD=your_password
SERVER=MetaQuotes-Demo
...

그 다음 인자 없이 서버를 시작하세요:

metatrader-http-server

서버가 .env 파일에서 자격 증명을 자동으로 로드합니다.

MCP 서버는 여러 전송 모드 (transport modes)를 지원합니다:

플래그 (Flag)	환경 변수 (Env Var)	기본값 (Default)	설명 (Description)
`--transport`	`MCP_TRANSPORT`	`sse`	전송 유형: `sse`, `stdio`, `streamable-http`
`--host`	`MCP_HOST`	`0.0.0.0`	바인딩할 호스트 (SSE/HTTP 전용)
`--port`	`MCP_PORT`	`8080`	바인딩할 포트 (SSE/HTTP 전용)

CLI 플래그 (CLI flags)는 환경 변수 (environment variables)보다 우선하며, 환경 변수는 기본값 (defaults)보다 우선합니다.

metatrader-http-server --host 127.0.0.1 --port 9000

MT5 클라이언트는 추가 설정을 지원합니다:

config = {
"login": 12345678,
"password": "your_password",
...

설정 옵션 (Configuration Options):

ariadng/metatrader-mcp-server

요약

핵심 포인트

댓글