# Borsa Mcp

> MCP Server for Turkish & American Stock Exchange and Fund Data

- **Type:** MCP server
- **Install:** `agentstack add mcp-saidsurucu-borsa-mcp`
- **Verified:** Pending review
- **Seller:** [saidsurucu](https://agentstack.voostack.com/s/saidsurucu)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [saidsurucu](https://github.com/saidsurucu)
- **Source:** https://github.com/saidsurucu/borsa-mcp

## Install

```sh
agentstack add mcp-saidsurucu-borsa-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Borsa MCP: Türk Finans Piyasaları için MCP Sunucusu

[](https://www.star-history.com/#saidsurucu/borsa-mcp&Date)

Borsa İstanbul (BIST) ve ABD (US) hisseleri, TEFAS fonları, kripto paralar ve döviz/emtia verilerine LLM'ler üzerinden erişim sağlayan [FastMCP](https://gofastmcp.com/) sunucusu. KAP, Yahoo Finance, BtcTurk, Coinbase, borsapy ve TCMB gibi kaynaklardan **26 birleşik araç** ile kapsamlı finansal analiz.

---

## ⚠️ Önemli Uyarılar

- **LLM'ler halüsinasyon yapabilir** - Verileri mutlaka doğrulayın
- **Yatırım tavsiyesi değildir** - Profesyonel danışmanlık alın
- **Eğitim amaçlıdır** - Sorumluluk size aittir

---

## 🚀 5 Dakikada Başla (Remote MCP)

**✅ Kurulum Gerektirmez! Hemen Kullan!**

🔗 **Remote MCP Adresi:** https://borsamcp.fastmcp.app/mcp

### Claude Desktop ile Kullanım (Ücretli abonelik gerekir)

1. **Claude Desktop**'ı açın
2. **Settings** → **Connectors** → **Add Custom Connector**
3. Bilgileri girin:
   - **Name:** `Borsa MCP`
   - **URL:** `https://borsamcp.fastmcp.app/mcp`
4. **Add** butonuna tıklayın
5. Hemen kullanmaya başlayın! 🎉

### Google Antigravity ile Kullanım

1. Agent session açın ve editörün yan panelindeki "…" dropdown menüsüne tıklayın
2. **MCP Servers** seçeneğini seçin - MCP Store açılacak
3. Üstteki **Manage MCP Servers** butonuna tıklayın
4. **View raw config** seçeneğine tıklayın
5. `mcp_config.json` dosyasına aşağıdaki yapılandırmayı ekleyin:

```json
{
  "mcpServers": {
    "borsa-mcp": {
      "serverUrl": "https://borsamcp.fastmcp.app/mcp",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}
```

💡 **İpucu:** Remote MCP sayesinde Python, uv veya herhangi bir kurulum yapmadan doğrudan Google Antigravity üzerinden Türk finans piyasalarına erişebilirsiniz!

**Örnek Sorular:**
```
GARAN hissesinin son 1 aylık performansını analiz et
XU100 endeksinin bugünkü durumunu göster
Bitcoin'in TRY fiyatını kontrol et
```

---

## 🎯 Temel Özellikler

**28 Birleşik Araç ile Kapsamlı Finansal Analiz (v0.9.0):**

* 📈 **Hisse Senetleri (BIST + US):** 758 BIST + tüm NYSE/NASDAQ şirketleri, tek araçla `market` parametresi ile
* 🔍 **Teknik Tarama:** BIST teknik scanner (RSI, MACD, Supertrend, T3) + US screener (23 preset)
* 🆕 **TCMB EVDS:** 145 kategori, on binlerce makro seri — faiz, döviz, ödemeler dengesi, enflasyon (`get_evds_data`, ücretsiz API key)
* 🆕 **Makro Veriler:** TCMB enflasyon verileri ve hesaplama araçları (`get_macro_data`)
* 🎯 **Pivot Points:** 3 direnç & 3 destek seviyesi hesaplama (klasik pivot formülü)
* 📊 **Endeksler:** BIST + US endeksleri tek araçla (`get_index_data`)
* 💡 **Değer Yatırımı:** Buffett analizi ve finansal sağlık araçları (ROE, ROIC, Altman Z-Score)
* 💰 **TEFAS Fonları:** 836+ fon, performans, portföy, karşılaştırma (`compare_mode`)
* ₿ **Kripto Paralar:** BtcTurk + Coinbase birleşik (`get_crypto_market`)
* 💱 **Döviz & Emtia:** 65 para birimi, altın, petrol (borsapy entegrasyonu)
* 📅 **Ekonomik Takvim:** TR, US, EU, DE, GB, JP, CN (7 ülke)
* ☪️ **Katılım Finans:** Katılım finans uygunluk bilgisi (`include_islamic` parametresi)
* 📰 **KAP Haberleri:** Liste + detay (`news_id` parametresi ile)
* 📋 **Yardım Araçları:** `get_screener_help`, `get_scanner_help`, `get_regulations`
* ⚡ **LLM Optimizasyonu:** İngilizce açıklamalar, domain-spesifik araç seçimi
* 🚀 **FastMCP 2.14:** Response Caching + Background Tasks

## 📑 İçindekiler

| Bölüm | Açıklama |
|-------|----------|
| [🚀 5 Dakikada Başla](#-5-dakikada-başla-remote-mcp) | Kurulum gerektirmez - Remote MCP |
| [🎯 Temel Özellikler](#-temel-özellikler) | 26 birleşik araç ile kapsamlı finansal analiz |
| [💻 Gelişmiş Kurulum](#-gelişmiş-kurulum-isteğe-bağlı) | 5ire, Claude Desktop local kurulum |
| [🛠️ Kullanılabilir Araçlar](#️-kullanılabilir-araçlar-mcp-tools) | BIST, US, Kripto, Döviz, Fon araçları |
| [🔍 Veri Kaynakları](#-veri-kaynakları--kapsam) | KAP, Yahoo Finance, BtcTurk, Coinbase, TCMB |
| [📊 Örnek Kullanım](#-örnek-kullanım) | Pratik sorgular ve analiz örnekleri |

---

## 💻 Gelişmiş Kurulum (İsteğe Bağlı)

**Not:** Remote MCP kullanıyorsanız bu adımları atlayabilirsiniz!

### 5ire ve Diğer MCP İstemcileri için Local Kurulum

Bu bölüm, Borsa MCP'yi 5ire gibi diğer MCP istemcileriyle local olarak kullanmak isteyenler içindir.

* **Python Kurulumu:** Sisteminizde Python 3.11 veya üzeri kurulu olmalıdır. Kurulum sırasında "**Add Python to PATH**" (Python'ı PATH'e ekle) seçeneğini işaretlemeyi unutmayın. [Buradan](https://www.python.org/downloads/) indirebilirsiniz.
* **Git Kurulumu (Windows):** Bilgisayarınıza [git](https://git-scm.com/downloads/win) yazılımını indirip kurun. "Git for Windows/x64 Setup" seçeneğini indirmelisiniz.
* **`uv` Kurulumu:**
    * **Windows Kullanıcıları (PowerShell):** Bir CMD ekranı açın ve bu kodu çalıştırın: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
    * **Mac/Linux Kullanıcıları (Terminal):** Bir Terminal ekranı açın ve bu kodu çalıştırın: `curl -LsSf https://astral.sh/uv/install.sh | sh`
* **Microsoft Visual C++ Redistributable (Windows):** Bazı Python paketlerinin doğru çalışması için gereklidir. [Buradan](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) indirip kurun.
* İşletim sisteminize uygun [5ire](https://5ire.app) MCP istemcisini indirip kurun.
* 5ire'ı açın. **Workspace -> Providers** menüsünden kullanmak istediğiniz LLM servisinin API anahtarını girin.
* **Tools** menüsüne girin. **+Local** veya **New** yazan butona basın.
    * **Tool Key:** `borsamcp`
    * **Name:** `Borsa MCP`
    * **Command:**
        ```
        uvx --from git+https://github.com/saidsurucu/borsa-mcp borsa-mcp
        ```
    * **Save** butonuna basarak kaydedin.
* Şimdi **Tools** altında **Borsa MCP**'yi görüyor olmalısınız. Üstüne geldiğinizde sağda çıkan butona tıklayıp etkinleştirin (yeşil ışık yanmalı).
* Artık Borsa MCP ile konuşabilirsiniz.

### Claude Desktop için Local Kurulum

**Not:** Remote MCP daha kolay bir seçenektir. Sadece local kurulum yapmak istiyorsanız bu adımları izleyin.

1.  **Ön Gereksinimler:** Python, `uv`, (Windows için) Microsoft Visual C++ Redistributable'ın sisteminizde kurulu olduğundan emin olun. Detaylı bilgi için yukarıdaki "5ire için Kurulum" bölümündeki ilgili adımlara bakabilirsiniz.
2.  Claude Desktop **Settings -> Developer -> Edit Config**.
3.  Açılan `claude_desktop_config.json` dosyasına `mcpServers` altına ekleyin. UYARI: // ile başlayan yorum satırını silmelisiniz:

    ```json
    {
      "mcpServers": {
        // ... (varsa diğer sunucularınız) ...
        "Borsa MCP": {
          "command": "uvx",
          "args": [
            "--from", "git+https://github.com/saidsurucu/borsa-mcp",
            "borsa-mcp"
          ]
        }
      }
    }
    ```
4.  Claude Desktop'ı kapatıp yeniden başlatın.

---

## 🛠️ Kullanılabilir Araçlar (MCP Tools)

Bu FastMCP sunucusu LLM modelleri için **26 birleşik araç** sunar. Tüm araçlar `market` parametresi ile BIST ve US piyasalarını destekler.

### Hisse Senedi Araçları (15 araç - BIST + US)
| Araç | Açıklama | Multi-ticker |
|------|----------|--------------|
| `search_symbol` | Hisse, endeks, fon, kripto sembol arama | - |
| `get_profile` | Şirket profili (sektör, açıklama, finansallar) + `include_islamic` | - |
| `get_quick_info` | Hızlı metrikler (P/E, P/B, ROE, 52h aralık) | ✅ |
| `get_historical_data` | OHLCV fiyat verileri (tarih aralığı desteği) | - |
| `get_technical_analysis` | RSI, MACD, Bollinger Bantları, hareketli ortalamalar | - |
| `get_pivot_points` | Destek/direnç seviyeleri (S1-S3, R1-R3) | - |
| `get_analyst_data` | Analist derecelendirmeleri ve fiyat hedefleri | ✅ |
| `get_dividends` | Temettü geçmişi, verim, dağıtım oranı | ✅ |
| `get_earnings` | Kazanç takvimi, EPS geçmişi, büyüme tahminleri | ✅ |
| `get_financial_statements` | Bilanço, gelir tablosu, nakit akışı | ✅ |
| `get_financial_ratios` | Değerleme, Buffett, sağlık, gelişmiş metrikler | - |
| `get_corporate_actions` | Sermaye artırımları, temettü geçmişi (BIST) | ✅ |
| `get_news` | KAP haberleri + `news_id` ile detay | - |
| `screen_securities` | 23 preset veya özel filtreler ile tarama | - |
| `scan_stocks` | Teknik scanner (RSI, MACD, Supertrend, T3) | - |

### Kripto Araçları (1 araç - BtcTurk + Coinbase)
| Araç | Açıklama |
|------|----------|
| `get_crypto_market` | Ticker, orderbook, trades, OHLC, borsa bilgileri |

### FX & Makro Araçları (4 araç)
| Araç | Açıklama |
|------|----------|
| `get_fx_data` | 65 para birimi, metaller, emtialar (borsapy) |
| `get_economic_calendar` | Ekonomik olaylar (TR, US, EU, DE, GB, JP, CN) |
| `get_bond_yields` | Devlet tahvil faizleri (TR 2Y, 5Y, 10Y) |
| `get_sector_comparison` | Sektör karşılaştırması ve ortalama metrikler |

### Fon & Endeks Araçları (2 araç)
| Araç | Açıklama |
|------|----------|
| `get_fund_data` | TEFAS fon verileri + `compare_mode` ile karşılaştırma |
| `get_index_data` | Borsa endeks verileri (BIST + US) |

### Makro & Yardım Araçları (5 araç)
| Araç | Açıklama |
|------|----------|
| `get_macro_data` | TCMB enflasyon verileri ve hesaplama (TÜFE/ÜFE, key gerekmez) |
| `get_evds_data` | TCMB EVDS — 145 kategori, on binlerce makro seri (rates, FX, BoP, expectation surveys); katalog/arama key gerekmez, veri çekme için `EVDS_API_KEY` env var (ücretsiz: https://evds3.tcmb.gov.tr) |
| `get_screener_help` | Screener presetleri ve filtre dokümantasyonu |
| `get_scanner_help` | BIST scanner göstergeleri ve presetler |
| `get_regulations` | Türk yatırım fonu mevzuatı |

#### 🔑 EVDS Kurulumu

`get_evds_data` aracının veri çekme işlemleri (`series`, `multi_series`, `datagroup_data`) için TCMB'den ücretsiz bir API anahtarı gerekir. Katalog gezintisi, arama ve dashboard listeleme anahtar gerektirmeden çalışır.

1. https://evds3.tcmb.gov.tr → "BENİM SAYFAM" → Kayıt Ol
2. Profilim → API Key Kopyala
3. Ortam değişkeni olarak ayarla:
   ```bash
   export EVDS_API_KEY="your-key-here"
   ```
   veya MCP server config'e ekle (Claude Desktop / Cursor):
   ```json
   {
     "mcpServers": {
       "borsa": {
         "command": "uv",
         "args": ["run", "borsa-mcp"],
         "env": { "EVDS_API_KEY": "your-key-here" }
       }
     }
   }
   ```

**Örnek kullanım:**
```python
get_evds_data(action="categories")                                            # 145 kategori
get_evds_data(action="search", keyword="dolar")                               # katalog araması
get_evds_data(action="series", series_code="TP.DK.USD.A.YTL", period="1y")    # USD/TRY günlük
get_evds_data(action="series", series_code="TP.FG.J0", formula="yoy_pct")     # TÜFE YoY%
get_evds_data(action="multi_series", series_codes=["TP.DK.USD.A.YTL","TP.DK.EUR.A.YTL"])
get_evds_data(action="datagroup_data", datagroup_code="bie_dkdovizgn")        # 137 seri tek çağrıda
```

---

## 🔍 Veri Kaynakları & Kapsam

### KAP (Kamuyu Aydınlatma Platformu)
- **Şirketler**: 758 BIST şirketi (ticker kodları, adlar, şehirler, çoklu ticker desteği)
- **Katılım Finans**: Resmi katılım finans uygunluk değerlendirmeleri
- **Güncelleme**: Otomatik önbellek ve yenileme

### Yahoo Finance Entegrasyonu
- **Endeks Desteği**: Tüm BIST endeksleri (XU100, XBANK, XK100 vb.) için tam destek
- **Zaman Dilimi**: Tüm zaman damgaları Avrupa/İstanbul'a çevrilir
- **Veri Kalitesi**: Büyük bankalar ve teknoloji şirketleri en iyi kapsama sahiptir
- **Tarih Aralığı Desteği**: Belirli tarihler arası sorgulama (YYYY-MM-DD formatında, örn: "2024-01-01" - "2024-12-31")
- **İki Sorgu Modu**:
  - **Dönem Modu:** Period parametresi ile (1d, 1mo, 1y, vb.) - varsayılan
  - **Tarih Modu:** start_date ve end_date parametreleri ile belirli tarih aralığı

### US Stock Market (Yahoo Finance)
- **Kapsam**: S&P 500, Nasdaq-100, Dow Jones ve NYSE'deki tüm şirketler
- **Endeksler**: 28 ana US endeksi (^GSPC, ^IXIC, ^DJI, Russell, sektör ETF'leri)
- **Kategoriler**: Large Cap, Tech, Blue Chip, Small Cap, Mid Cap, International
- **Finansal Tablolar**: Quarterly ve annual balance sheet, income statement, cash flow
- **Değer Analizi**: Buffett analizi için US 10Y Treasury (^TNX) ve Fed %2.5 enflasyon hedefi
- **Güncelleme**: Gerçek zamanlı piyasa verileri

### US Stock Screener (yfscreen paketi)
- **Varlık Türleri**: Hisse senedi (equity), ETF ve yatırım fonları (mutual funds)
- **Preset Sayısı**: 23 hazır tarama şablonu (18 hisse + 3 ETF + 2 yatırım fonu)
- **Filtre Alanları**: 96+ hisse senedi, 29 ETF, 28 yatırım fonu filtre alanı
- **Operatörler**: eq (eşit), gt (büyük), lt (küçük), btwn (arasında)
- **Özel Filtreler**: Kullanıcı tanımlı filtreler ile gelişmiş tarama
- **Akıllı Alan Dönüşümü**: ETF/fund taramalarında equity alanları otomatik dönüştürülür
- **Otomatik Region**: Custom filter kullanırken `region=us` otomatik eklenir
- **Sayfalama**: Offset/limit ile büyük sonuç setlerinde navigasyon
- **Performans**: Yahoo Finance screener API entegrasyonu, hızlı sonuçlar

### BIST Hisse Tarayıcı (borsapy paketi)
- **Veri Kaynağı**: İş Yatırım gelişmiş hisse arama (borsapy kütüphanesi)
- **Preset Sayısı**: 15 hazır tarama şablonu (piyasa değeri, değer, temettü, momentum, hacim, yabancı, analist)
- **Filtre Kriteri**: 50+ filtre (13 kategori: değerleme, kârlılık, temettü, getiri, piyasa, yabancı, analist, endeks)
- **Operatörler**: min (minimum), max (maximum) ile aralık filtreleme
- **Özel Filtreler**: Kullanıcı tanımlı filtreler ile gelişmiş tarama
- **Otomatik Birim Dönüşümü**: Piyasa değeri ve hacim için TL → milyon TL otomatik dönüşüm
- **Sayfalama**: Offset/limit ile büyük sonuç setlerinde navigasyon
- **Performans**: İş Yatırım API entegrasyonu, hızlı sonuçlar
- **Güncelleme**: Gerçek zamanlı BIST verileri

### Mynet Finans (Hibrit Mod)
- **Türk Özel Verileri**: Kurumsal yönetim, ortaklık yapısı, bağlı şirketler
- **KAP Haberleri**: Gerçek zamanlı resmi duyuru akışı
- **Endeks Kompozisyonu**: Canlı endeks şirket listeleri

### TEFAS (Türkiye Elektronik Fon Alım Satım Platformu)
- **Fon Evreni**: 800+ Türk yatırım fonu
- **Resmi API**: TEFAS BindHistoryInfo ve BindHistoryAllocation API'leri
- **Kategori Filtreleme**: 13 fon kategorisi (borçlanma, hisse senedi, altın vb.)
- **Performans Metrikleri**: 7 dönemlik getiri analizi (1 günlük - 3 yıllık)
- **Portföy Analizi**: 50+ Türk varlık kategorisi ile detaylı dağılım
- **Güncellik**: Gerçek zamanlı fon fiyatları ve performans verileri

### Fon Mevzuatı
- **Kaynak**: `fon_mevzuat_kisa.md` - 80,820 karakter düzenleme metni
- **Kapsam**: Yatırım fonları için kapsamlı Türk mevzuatı
- **İçerik**: Portföy limitleri, fon türleri, uyumluluk kuralları
- **Güncelleme**: Dosya metadata ile son güncelleme tarihi

### BtcTurk Kripto Para Borsası (Türk Piyasası)
- **İşlem Çiftleri**: 295+ kripto para işlem çifti (ana TRY ve USDT piyasaları dahil)
- **Para Birimleri**: 158+ desteklenen kripto para ve fiat para birimi (BTC, ETH, TRY, USDT vb.)
- **API Endpoint**: Resmi BtcTurk Public API v2 (https://api.btcturk.com/api/v2)
- **Piyasa Verileri**: Gerçek zamanlı ticker fiyatları, emir defterleri, işlem geçmişi, OHLC/Kline grafikleri
- **Türk Odak**: TRY çiftleri için optimize edilmiş (BTCTRY, ETHTRY, ADATRY vb.)
- **Güncelleme Sıklığı**: Borsa bilgileri için 1 dakika önbellek ile gerçek zamanlı piyasa verileri
- **Veri Kalitesi**: Milisaniye hassasiyetli zaman damgaları ile profesyonel seviye borsa verileri

### Coinbase Global Kripto Para Borsası (Uluslararası Piyasalar)
- **İşlem Çiftleri**: 500+ global kripto para işlem çifti (ana USD, EUR ve GBP piyasaları dahil)
- **Para Birimleri**: 200+ desteklenen kripto para ve fiat para birimi (BTC, ETH, USD, EUR, GBP vb.)
- **API Endpoint**: Resmi Coinbase Advanced Trade API v3 ve App API v2 (https://api.coinbase.com)
- **Piyasa Verileri**: Gerçek zamanlı ticker fiyatları, emir defterleri, işlem geçmişi, OHLC/mum grafikleri, sunucu zamanı
- **Global Odak**: Uluslararası piyasalar için USD/EUR çiftleri (BTC-USD, ETH-EUR vb.)
- **Güncelleme Sıklığı**: Borsa bilgileri için 5 dakika önbellek ile gerçek zamanlı piyasa verileri
- *

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [saidsurucu](https://github.com/saidsurucu)
- **Source:** [saidsurucu/borsa-mcp](https://github.com/saidsurucu/borsa-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-saidsurucu-borsa-mcp
- Seller: https://agentstack.voostack.com/s/saidsurucu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.