tor-mcp

.onion / dark web araştırması için bir MCP sunucusu. Yetkili tehdit istihbaratı, kırmızı takım ve güvenlik araştırması içindir.

Bu sunucu işi sıfırdan yapmaz. OpenTor skill'inin motorunu Model Context Protocol üzerinden dışarı açar. MCP açık bir protokol olduğu için sunucu model bağımsızdır: Cursor, VS Code, Zed, Cline, Continue, OpenAI Agents SDK, LangChain gibi MCP konuşan her istemci ve tool-calling yapabilen her model kullanabilir.

Neden sarmalayıcı, neden kopya değil: motor kodunda reklam filtreleme, diferansiyel kalibrasyon, ayna birleştirme ve açıklanabilir sıralama gibi kırılgan bilgi birikmiş. İkinci bir kopya tutmak iki ayrı yerde bakım yapmak demek olurdu.

Gereksinimler

Gereksinim	Not
Python 3.10+
OpenTor motoru	Konumu OPENTOR_SKILL_ROOT ile belirtilir
Tor SOCKS proxy	Çalışıyor olmalı, sunucu Tor'u kendisi başlatmaz

Sunucu, skill'in .env dosyasındaki TOR_SOCKS_PORT ayarını kullanır.

• 9050: bağımsız tor.exe veya Tor Expert Bundle
• 9150: Tor Browser (açık kalmalı)

OPENTOR_SKILL_ROOT ortam değişkenini OpenTor motorunun bulunduğu klasöre ayarla.

Kurulum

git clone https://github.com/ilkerK01/tor-mcp.git
cd tor-mcp
python -m venv .venv

Linux / macOS:

.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python selftest.py

Windows:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe selftest.py

ALL CHECKS PASSED görmelisin. Tor kapalıysa ağ tool'ları atlanır, geri kalan her şey yine test edilir.

İstemciye bağlama

Aşağıdaki yollarda /path/to/tor-mcp kısmını kendi klasörünle değiştir.

Elle JSON (Cursor, Zed, Cline, VS Code vb.)

{
  "mcpServers": {
    "tor-mcp": {
      "command": "/path/to/tor-mcp/.venv/bin/python",
      "args": ["/path/to/tor-mcp/server.py"]
    }
  }
}

Windows'ta command alanı C:\\path\\to\\tor-mcp\\.venv\\Scripts\\python.exe olur.

Windows yol notu: Kullanıcı adında ASCII dışı karakter varsa (ör. Türkçe İ, ş, ğ) UTF-8 okumayan araçlar yolu bozup süreci dosyayı bulamadan öldürebilir. Bu durumda dir /x ile 8.3 kısa yolunu öğrenip onu kullan.

Tool'lar (14)

Bağlantı

Tool	İş
tor_status	Tor bağlı mı, çıkış IP'si ne. Her oturumda önce bunu çağır.
tor_new_identity	Devreyi yenile, yeni çıkış düğümü al. Kontrol portu 9051 gerekir.

Arama

Tool	İş
onion_search	12 motorda ara. Reklam ve sayfa mobilyası ayıklanmış, tekilleştirilmiş, skorlanmış sonuç döner.
list_engines	Motor ve analiz modu listesi
engine_health	Tüm motorları pingle, up/down ve gecikme raporla

Çekme

Tool	İş
onion_fetch	Tek URL'yi Tor üzerinden çek, metne çevir
onion_batch_fetch	Birden çok URL'yi paralel çek
triage_results	Hangi sonuçlar gerçekten canlı, ölüleri ele ve canlıları öne al

Analiz

Tool	İş
extract_iocs	Hash, IP, domain, e-posta, CVE, kripto cüzdanı, ATT&CK tekniği, mesajlaşma handle'ı çıkarır
plan_queries	Tek hedefi çeşitli bir sorgu setine genişletir
classify_target	Hedefin türünü belirler (domain, e-posta, onion, aktör adı)

Soruşturma

Tool	İş
investigate	Çok turlu soruşturma: ara, pivotla, dosya çıkar. Bütçe sınırlı.
crawl_onion	Bir .onion sitesini öncelik güdümlü tarar, yapısını çıkarır
export_findings	JSON, CSV, STIX, MISP veya düz metin olarak dışa verir

Analiz modları

onion_search, plan_queries ve investigate bir mode parametresi alır. Mod, hangi motorların kullanılacağını ve sorguların nasıl genişletileceğini belirler.

• threat_intel: genel tehdit istihbaratı, tüm motorlar
• ransomware: fidye yazılımı sızıntı siteleri, bilinen tohum adresler dahil
• personal_identity: kimlik ve kimlik bilgisi sızıntısı
• corporate: kurumsal maruziyet

Tipik akış

1. tor_status                     bağlantıyı doğrula
2. engine_health                  kaç motor ayakta (az sonuç gelirse sebebi budur)
3. plan_queries(hedef, mode)      sorgu setini gör
4. onion_search(sorgu, mode)      sonuçları topla
5. triage_results(sonuclar)       ölü adresleri ele
6. onion_batch_fetch(canli_urls)  içerikleri çek
7. extract_iocs(metin)            IOC çıkar
8. export_findings(..., "misp")   platforma teslim et

Kestirme yol: investigate(hedef, mode) 3 ile 7 arasını tek çağrıda yapar.

Dikkat edilecekler

Süre. Tor üzerinden her istek 30 ile 60 saniye sürer. onion_search motorları paralel sorgular ama yine de bir dakikayı bulabilir. investigate varsayılan olarak 240 saniyelik sert bir bütçeyle çalışır, çünkü çoğu MCP istemcisinin zaman aşımı bunun üstündedir. Bütçe dolunca kısmi dosya döner, hiçbir şey kaybolmaz.

Ölü adresler normaldir. Sızıntı siteleri sürekli adres değiştirir. triage_results tam olarak bunun için var.

Sonuç azsa önce motorları kontrol et. .onion arama motorlarının yarısının aynı anda kapalı olması olağandır. "Bu konuda hiçbir şey yok" demeden önce engine_health çalıştır.

Tokenizasyon önemli. Motorlar niyeti değil token'ı indeksler. Bitişik, boşluklu ve tireli formlar farklı sonuç verir. Bir şeyin indekste olmadığına karar vermeden önce üçünü de dene.

Gözlem yorum değildir. investigate bir dosya döner, hüküm vermez. Bir sızıntının gerçek mi yoksa yeniden satılan eski bir dump mı olduğuna karar vermek çağıranın işidir.

Kapsam. Yetkili tehdit istihbaratı, kırmızı takım ve güvenlik araştırması içindir. Sunucu yasa dışı içeriği filtreler ama asıl sınırı kullanan çizer.

Sorun giderme

Belirti	Sebep ve çözüm
Tor SOCKS proxy is not reachable	Tor kapalı. 9150 ise Tor Browser'ı aç, 9050 ise tor sürecini başlat.
tor_new_identity hata veriyor	Kontrol portu 9051 torrc içinde açık değil
Arama boş dönüyor	engine_health çalıştır, motorlar düşmüş olabilir
OpenTor skill not found	OPENTOR_SKILL_ROOT değişkenini skill klasörüne ayarla
Sunucu hiç açılmıyor	selftest.py çalıştır ve hatayı oku

Dosyalar

tor-mcp/
├── server.py         MCP sunucusu, 14 tool
├── selftest.py       Tor'suz çalışan doğrulama testi
├── requirements.txt
├── LICENSE
└── README.md

Veritabanı ve bulgu defteri skill ile ortaktır (<skill>/database/opentor.db). Yani MCP üzerinden yaptığın araştırma, skill üzerinden yaptığınla aynı hafızayı paylaşır. Bu dosya repoya dahil değildir.

Lisans

MIT. Ayrıntı için LICENSE dosyasına bak.