---

📑 İçindekiler

• Bu Nedir?
• Özellikler
• Bu Kim İçin?
• Önemli Uyarı
• Ön Koşullar
• Hızlı Başlangıç
• Ticaret Asistanı Becerisi
• Kullanım Örnekleri
• Mevcut İşlemler
• WebSocket Fiyat Sunucusu
• Gelişmiş Yapılandırma
• Yol Haritası
• Geliştirme
• Katkıda Bulunma
• Dokumentasyon
• Yardım Almak
• Lisans

---

🌟 Bu Nedir?

MetaTrader MCP Sunucusu, AI asistanlarını (Claude, ChatGPT gibi) MetaTrader 5 ticaret platformuna bağlayan bir köprüdür. Düğmeleri tıklamak yerine, AI asistanınıza ne yapması gerektiğini söyleyebilirsiniz:

"Hesap bakiyemi göster" "0.01 lot EUR/USD satın al" "Tüm kârlı pozisyonları kapat"

AI request'inizi anlar ve MetaTrader 5'te otomatik olarak çalıştırır.

Nasıl Çalışır?

Siz → AI Asistanı → MCP Sunucusu → MetaTrader 5 → Ticaret İşlemleriniz

✨ Özellikler

• 🗣️ Doğal Dil Ticareti - Ticaret işlemleri için AI'ye düz İngilizce konuşun
• 🤖 Multi-AI Desteği - Claude Desktop, ChatGPT (Open WebUI üzerinden) ve daha fazlası ile çalışır
• 📊 Tam Pazar Erişimi - Gerçek zamanlı fiyatlar, tarihsel veriler ve sembol bilgisi alın
• 💼 Tam Hesap Kontrolü - Bakiye, öz kaynaklar, marj ve ticaret istatistiklerini kontrol edin
• ⚡ Emir Yönetimi - Emirleri yerleştirin, değiştirin ve kapatın
• 🔒 Güvenli - Tüm kimlik bilgileri makinenizde kalır
• 🌐 Esnek Arayüzler - MCP sunucusu, REST API veya WebSocket akışı olarak kullanın
• 📖 İyi Belgelenmiş - Kapsamlı kılavuzlar ve örnekler

🎯 Bu Kim İçin?

• Yatırımcılar - AI kullanarak ticaretlerini otomatik hale getirmek isteyen
• Geliştiriciler - Ticaret botları veya analiz araçları oluşturayanlar
• Analistler - Pazar verilerine hızlı erişim gerektiren
• Herkes - AI'yı finansal piyasalarla birleştirmekle ilgilenen

⚠️ Önemli Uyarı

Bunu dikkatlice okuyun:

Finansal araçlarla ticaret önemli kayıp riski taşır. Bu yazılım olduğu gibi sağlanır ve geliştiriciler bu yazılımın kullanılmasından kaynaklanan herhangi bir ticaret kaybı, kazancı veya sonucu için sorumluluk kabul etmez.

Bu yazılımı kullanarak şunları kabul etmiş olursunuz:

• Finansal ticaretin risklerini anladığınızı
• Bu sistem aracılığıyla yürütülen tüm işlemlerden siz sorumlusunuz
• Geliştiricileri herhangi bir sonuç için sorumlu tutmayacağınızı
• Bu yazılımı kendi riski altında kullandığınızı

Bu finansal tavsiye değildir. Her zaman sorumlu bir şekilde ticaret yapın.

---

📋 Ön Koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

1. Python 3.10 veya daha yüksek - Buradan indirin
2. MetaTrader 5 terminali - Buradan indirin
3. MT5 Ticaret Hesabı - Demo veya gerçek hesap kimlik bilgileri
   • Giriş numarası
   • Şifre
   • Sunucu adı (örneğin, "MetaQuotes-Demo")

🚀 Hızlı Başlangıç

Adım 1: Paketi Yükleyin

Terminal veya komut istemi açın ve çalıştırın:

pip install metatrader-mcp-server

Adım 2: Algoritmik Ticareti Etkinleştirin

1. MetaTrader 5'i açın
2. Araçlar → Seçenekler adresine gidin
3. Expert Advisors sekmesini tıklayın
4. Algoritmic trading' için izin ver kutusunu işaretleyin
5. Tamam düğmesine tıklayın

Adım 3: Arayüzünüzü Seçin

Nasıl kullanmak istediğinize bağlı olarak birini seçin:

Seçenek A: Claude Desktop ile Kullanın (Yerel STDIO)

1. Claude Desktop config dosyasını bulun:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Dosyayı açın ve bu yapılandırmayı ekleyin:

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio"
      ]
    }
  }
}

Seçenek: Özel MT5 Terminal Yolunu Belirtin

MT5 terminaliniz standart olmayan bir konuma kuruluysa, --path parametresini ekleyin:

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio",
        "--path",      "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
      ]
    }
  }
}

3. YOUR_MT5_LOGIN, YOUR_MT5_PASSWORD ve YOUR_MT5_SERVER değerlerini gerçek kimlik bilgilerinizle değiştirin

4. Claude Desktop'ı yeniden başlatın

5. Sohbete başlayın! Deneyin: "Hesap bakiyem nedir?"

Seçenek B: Open WebUI ile Kullanın (ChatGPT ve diğer LLM'ler için)

1. HTTP sunucusunu başlatın:

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

Seçenek: Özel MT5 Terminal Yolunu Belirtin

MT5 terminaliniz standart olmayan bir konuma kuruluysa, --path parametresini ekleyin:

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

2. Tarayıcınızda http://localhost:8000/docs adresine giderek API belgelerine bakın

3. Open WebUI'da:

   • Ayarlar → Araçlar adresine gidin
   • Araç Sunucusu Ekle öğesine tıklayın
   • http://localhost:8000 girin
   • Kaydedin

4. Artık Open WebUI sohbetlerinizde ticaret araçlarını kullanabilirsiniz!

Seçenek C: WebSocket üzerinden Gerçek Zamanlı Fiyatlar

Canlı tick verilerini (bid, ask, spread, volume) panolar, botlar veya izleme için WebSocket üzerinden aktarın:

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

Herhangi bir WebSocket istemcisi ile bağlantı kurun:

websocat ws://localhost:8765

connected mesajı ve ardından sürekli tick güncellemelerini JSON olarak alacaksınız. Tüm ayrıntılar için WebSocket Fiyat Sunucusu bölümüne bakın.

Seçenek D: Uzak MCP Sunucusu (SSE)

MCP sunucusunu Windows VPS'sinde (MT5'in kurulu olduğu) çalıştırın ve Claude Desktop veya Claude Code'dan uzaktan bağlanın.

Sunucu tarafı (Windows VPS üzerinde):

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

Bu, varsayılan olarak SSE sunucusunu 0.0.0.0:8080 adresinde başlatır. --host ve --port ile özelleştirin:

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

İstemci tarafı (yerel makinenizde Claude Desktop config):

{
  "mcpServers": {
    "metatrader": {
      "url": "http://VPS_IP:8080/sse"
    }
  }
}

VPS_IP kısmını sunucunuzun IP adresi ile değiştirin.

Güvenlik Uyarısı: MCP protokolü kimlik doğrulama içermez. SSE sunucusunu ağ üzerinden açığa çıkarırken, erişimi IP ile sınırlamak için bir firewall kullanın veya kimlik doğrulama olan ters proxy'nin arkasına yerleştirin ya da SSH tüneli kullanın.

---

🤖 Ticaret Asistanı Becerisi (Claude Code / Claude Desktop)

claude-skill/ dizininde önceden oluşturulmuş bir Ticaret Terminali Asistanı becerisi bulunur. Claudeye tüm 32 ticaret aracı, çıktı biçimlendirmesi ve MetaTrader 5 domain uzmanlığı hakkında yapılandırılmış bilgi sağlar.

Claude Code için Kurulum

Seçenek 1: Symlink (önerilir)

Standart Claude Code beceri dizininden claude-skill/ dizinine symlink oluşturun:

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

Beceri otomatik olarak keşfedilecek ve /trading olarak kullanılabilir olacaktır.

Seçenek 2: Kopyala

Beceri dosyalarını Claude Code beceri dizinine kopyalayın:

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

Claude Desktop için Kurulum

Claude Desktop için, beceriyi global Claude beceri dizinine kopyalayın:

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

# Windows
mkdir "%APPDATA%\Claude\skills"
xcopy /E claude-skill\trading "%APPDATA%\Claude\skills\trading\"

Beceri Neler Yapar?

• Doğrudan Yürütme: İstenenler doğrultusunda ticaret işlemlerini hemen yürütür, ekstra onay gerekmez
• İşlemler: Karmaşık işlemler için araçları zincirlemeyi bilir (örneğin, pazar emri yerleştir sonra SL/TP ayarla)
• Biçimlendirme: Hesap verilerini, pozisyonları, emirleri ve fiyatları temiz terminal tarzı tablolarda sunar
• Domain Bilgisi: MT5 emir türlerini, zaman dilimlerini, sembol biçimlerini ve doldurma modlarını anlar

Kullanım

Bir kez kurulduktan sonra /trading ile çağırın veya doğrudan ticaret ile ilgili soruları sorun:

/trading
> Hesap panom göster
> 1.0800'de SL ile 0.1 lot EURUSD satın al
> Tüm kârlı pozisyonları kapat
> GBPUSD H4 mumlarını göster

---

📡 WebSocket Fiyat Sunucusu

WebSocket Fiyat Sunucusu, MetaTrader 5'ten gerçek zamanlı tick verilerini herhangi bir WebSocket istemcisine akıtır. Canlı panolar, algoritmik ticaret frontendleri ve gerçek zamanlı izleme için idealdir.

Sunucuyu Başlatma

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

Sunucu varsayılan olarak ws://0.0.0.0:8765 adresinde başlar.

Özelleştirme

metatrader-quote-server \
  --login YOUR_LOGIN \
  --password YOUR_PASSWORD \
  --server YOUR_SERVER \
  --host 127.0.0.1 \
  --port 9000 \
  --symbols "EURUSD,GBPUSD,XAUUSD" \
  --poll-interval 200

Yapılandırma

Bayrak	Çevre Değişkeni	Varsayılan	Açıklama
--host	QUOTE_HOST	0.0.0.0	Bağlanacak host
--port	QUOTE_PORT	8765	Bağlanacak port
--symbols	QUOTE_SYMBOLS	XAUUSD,USOIL,GBPUSD,USDJPY,EURUSD,BTCUSD	Akış yapılacak semboller (virgülle ayrılmış)
--poll-interval	QUOTE_POLL_INTERVAL_MS	100	Tick yoklama aralığı (milisaniye)

CLI bayrakları çevre değişkenlerinden öncelikli olup, çevre değişkenleri varsayılan değerlerden önceliklidir.

İleti Biçimi

Bağlantıda — sunucu, sembol listesi ile connected mesajı gönderir ve ardından önbelleğe alınmış tikleri gönderir:

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

Tick güncellemeleri — bid, ask veya volume değiştiğinde gönderilir:

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

Hatalar — bir sembol alınamazsa gönderilir:

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

Örnek: Python ile Bağlanma

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

async def main():
    async with connect("ws://localhost:8765") as ws:
        async for message in ws:
            tick = json.loads(message)
            if tick["type"] == "tick":
                print(f"{tick['symbol']}: {tick['bid']}/{tick['ask']} (spread: {tick['spread']})")

asyncio.run(main())

Tasarım Notları

• Değişim algılaması: Bid, ask veya volume gerçekten değiştiğinde yalnızca yayın yapar ve gereksiz trafiği azaltır.
• Geç katılanlar: Yeni istemciler bağlanır bağlanmaz önbelleğe alınmış tikleri alırlar, bu nedenle sonraki değişimi beklemelerine gerek kalmaz.
• MT5 thread güvenliği: Tüm MT5 SDK çağrıları eşzamanlı erişim sorunlarını önlemek için tek iş parçacığı yürütücüsü aracılığıyla serileştirilir.
• Birden çok istemci: Herhangi bir sayıda WebSocket istemcisi aynı anda bağlanabilir.

---

💡 Kullanım Örnekleri

Claude Desktop ile

Yapılandırıldıktan sonra doğal olarak sohbet edebilirsiniz:

Hesap Bilgisini Kontrol Edin:

Siz: "Hesap bilgilerimi göster"

Claude: Bakiye, öz kaynaklar, marj, kaldıraç vb. döndürür

Pazar Verilerini Alın:

Siz: "EUR/USD'nin güncel fiyatı nedir?"

Claude: Bid, ask ve spreadi gösterir

Ticaret Yapın:

Siz: "GBP/USD'nin 0.01 lotunu 1.2500 stop loss ve 1.2700 take profit ile satın al"

Claude: Ticaret işlemini yürütür ve onaylar

Pozisyonları Yönetin:

Siz: "Kayıplı tüm pozisyonlarımı kapat"

Claude: Pozisyonları kapatır ve sonuçları raporlar

Geçmişi Analiz Edin:

Siz: "Geçen haftamın EUR/USD için tüm ticaretlerini göster"

Claude: Ticaret geçmişini tablo olarak döndürür

HTTP API ile

# Hesap bilgisini al
curl http://localhost:8000/api/v1/account/info

# Güncel fiyat al
curl "http://localhost:8000/api/v1/market/price?symbol_name=EURUSD"

# Pazar emri yerleştir
curl -X POST http://localhost:8000/api/v1/order/market \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "volume": 0.01,
    "type": "BUY",
    "stop_loss": 1.0990,
    "take_profit": 1.1010
  }'

# Tüm açık pozisyonları al
curl http://localhost:8000/api/v1/positions

# Spesifik bir pozisyonu kapat
curl -X DELETE http://localhost:8000/api/v1/positions/12345

Python Kütüphanesi Olarak

from metatrader_client import MT5Client

# MT5'e bağlan
config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo"
}
client = MT5Client(config)
client.connect()

# Hesap istatistiklerini al
stats = client.account.get_trade_statistics()
print(f"Bakiye: ${stats['balance']}")
print(f"Öz Kaynaklar: ${stats['equity']}")

# Güncel fiyat al
price = client.market.get_symbol_price("EURUSD")
print(f"EUR/USD Bid: {price['bid']}, Ask: {price['ask']}")

# Pazar emri yerleştir
result = client.order.place_market_order(
    type="BUY",
    symbol="EURUSD",
    volume=0.01,
    stop_loss=1.0990,
    take_profit=1.1010
)
print(result['message'])

# Tüm pozisyonları kapat
client.order.close_all_positions()

# Bağlantıyı kes
client.disconnect()

---

📚 Mevcut İşlemler

Hesap Yönetimi

• get_account_info - Bakiye, öz kaynaklar, kâr, marj seviyesi, kaldıraç, para birimi alın

Pazar Verisi

• get_symbols - Mevcut tüm ticaret sembollerini listele
• get_symbol_price - Bir sembol için güncel bid/ask fiyatını al
• get_candles_latest - Son fiyat mumlarını al (OHLCV verisi)
• get_candles_by_date - Tarih aralığı için tarihsel mumları al
• get_symbol_info - Sembol hakkında detaylı bilgi al

Emir Yürütme

• place_market_order - Anında BUY/SELL emirleri yürüt
• place_pending_order - Gelecekteki yürütme için limit/stop emirleri yerleştir
• modify_position - Stop loss veya take profit'i güncelle
• modify_pending_order - Beklemede olan emir parametrelerini değiştir

Pozisyon Yönetimi

• get_all_positions - Tüm açık pozisyonları görüntüle
• get_positions_by_symbol - Pozisyonları ticaret çiftine göre filtrele
• get_positions_by_id - Spesifik pozisyon detaylarını al
• close_position - Spesifik bir pozisyonu kapat
• close_all_positions - Tüm açık pozisyonları kapat
• close_all_positions_by_symbol - Bir sembol için tüm pozisyonları kapat
• close_all_profitable_positions - Yalnızca kazançlı işlemleri kapat
• close_all_losing_positions - Yalnızca kayıplı işlemleri kapat

Beklemede Olan Emirler

• get_all_pending_orders - Tüm beklemede olan emirleri listele
• get_pending_orders_by_symbol - Beklemede olan emirleri sembol'e göre filtrele
• cancel_pending_order - Spesifik bir beklemede olan emri iptal et
• cancel_all_pending_orders - Tüm beklemede olan emirleri iptal et
• cancel_pending_orders_by_symbol - Bir sembol için beklemede olan emirleri iptal et

Ticaret Geçmişi

• get_deals - Geçmiş tamamlanmış işlemleri al
• get_orders - Geçmiş emir kayıtlarını al

---

🔧 Gelişmiş Yapılandırma

Çevre Değişkenleri Kullanma

Kimlik bilgilerini komut satırına koymak yerine, bir .env dosyası oluşturun:

LOGIN=12345678
PASSWORD=your_password
SERVER=MetaQuotes-Demo

# Seçenel: Özel MT5 terminal yolunu belirt (sağlanmazsa otomatik algılanır)
# MT5_PATH=C:\Program Files\MetaTrader 5\terminal64.exe

Ardından sunucuyu argüman olmadan başlatın:

metatrader-http-server

Sunucu otomatik olarak .env dosyasından kimlik bilgilerini yükleyecektir.

MCP Taşıma Yapılandırması

MCP sunucusu çoklu taşıma modlarını destekler:

Bayrak	Çevre Değişkeni	Varsayılan	Açıklama
--transport	MCP_TRANSPORT	sse	Taşıma türü: sse, stdio, streamable-http
--host	MCP_HOST	0.0.0.0	Bağlanacak host (SSE/HTTP sadece)
--port	MCP_PORT	8080	Bağlanacak port (SSE/HTTP sadece)

CLI bayrakları çevre değişkenlerinden öncelikli olup, çevre değişkenleri varsayılan değerlerden önceliklidir.

Özel Port ve Host (HTTP API)

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

Bağlantı Parametreleri

MT5 istemcisi ek yapılandırmayı destekler:

config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo",
    "path": None,               # MT5 terminal yürütülebilir yolu (varsayılan: otomatik algıla)
    "timeout": 60000,           # Bağlantı zaman aşımı (milisaniye) (varsayılan: 60000)
    "portable": False,          # Taşınabilir modu kullan (varsayılan: False)
    "max_retries": 3,           # Maksimum bağlantı yeniden deneme sayısı (varsayılan: 3)
    "backoff_factor": 1.5,      # Yeniden deneme arasındaki gecikme çarpanı (varsayılan: 1.5)
    "cooldown_time": 2.0,       # Bağlantılar arasında beklenecek saniye (varsayılan: 2.0)
    "debug": True               # Debug günlüğünü etkinleştir (varsayılan: False)
}

Yapılandırma Seçenekleri:

• login (int, gerekli): MT5 hesap giriş numaranız
• password (str, gerekli): MT5 hesap şifreniz
• server (str, gerekli): MT5 sunucu adı (örneğin, "MetaQuotes-Demo")
• path (str, seçienel): MT5 terminal yürütülebilir dosyasının tam yolu. Belirtilmezse, istemci standart kur