# fonlar-mcp

Türkiye'deki yatırım fonlarının (TEFAS) verilerini Claude'a sunan **Model Context Protocol** sunucusu.

Claude Desktop veya Claude Code üzerinden doğrudan TEFAS'a sorgu atmanı sağlar:

> "AAK fonunun son fiyatı ve 1 yıllık getirisi nedir?"
>
> "GO9 ve TTE fonlarını portföy ve performans olarak karşılaştır."
>
> "İçinde 'altın' geçen fonları listele."

## Özellikler

- **Kimlik bilgisi gerektirmez** — TEFAS'ın public API'sini kullanır.
- **Stdio transport** — yerel makinede çalışır, dışarı port açmaz.
- **Rate-limit dostu** — TEFAS'ın 6 req/dk sınırına otomatik saygı.
- **6 araç + 2 kaynak + 1 hazır prompt** sunar.

## Araçlar (Tools)

| Tool | Açıklama |
|------|----------|
| `get_fon_fiyat(fon_kodu)` | Güncel fiyat, günlük getiri, portföy büyüklüğü |
| `get_fon_fiyat_gecmisi(fon_kodu, periyod)` | Hafta / 1ay / 3ay / 6ay / 1yıl / 3yıl / 5yıl geçmiş |
| `get_fon_portfoy(fon_kodu, tarih?)` | Kategori bazlı portföy dağılımı |
| `karsilastir_fonlar(fon_1, fon_2, periyod)` | İki fonun getiri ve portföy karşılaştırması |
| `ara_fon(metin, limit)` | Fon kodu / ünvan araması |
| `donemsel_getiri_ozeti(fon_kodu)` | 1a/3a/6a/yb/1y/3y/5y getiri tablosu |

## Kurulum

### 1. Bağımlılıkları kur

```bash
git clone https://github.com/maku-cpu/fonlar-mcp.git
cd fonlar-mcp
uv sync
```

`uv` yüklü değilse: <https://docs.astral.sh/uv/getting-started/installation/>

### 2. Claude Desktop'a ekle

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) veya
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "fonlar": {
      "command": "uv",
      "args": [
        "--directory", "/MUTLAK/PATH/fonlar-mcp",
        "run", "fonlar-mcp"
      ]
    }
  }
}
```

Claude Desktop'u kapat-aç. Sağ alttaki bağlantı ikonunda `fonlar` görünmeli.

### 3. Claude Code'a ekle

```bash
claude mcp add fonlar -- uv --directory /MUTLAK/PATH/fonlar-mcp run fonlar-mcp
```

veya proje kökünde `.mcp.json`:

```json
{
  "mcpServers": {
    "fonlar": {
      "command": "uv",
      "args": ["--directory", "/MUTLAK/PATH/fonlar-mcp", "run", "fonlar-mcp"]
    }
  }
}
```

## Diğer MCP Client'larla Kullanım

MCP standart bir protokol — Claude'a özel değil. `fonlar-mcp` aşağıdaki tüm
client'larla **aynı server kodu** ile çalışır, sadece config dosyasının
yeri/formatı değişir.

### Cursor

`~/.cursor/mcp.json` veya proje kökünde `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "fonlar": {
      "command": "uv",
      "args": ["--directory", "/MUTLAK/PATH/fonlar-mcp", "run", "fonlar-mcp"]
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "fonlar": {
      "command": "uv",
      "args": ["--directory", "/MUTLAK/PATH/fonlar-mcp", "run", "fonlar-mcp"]
    }
  }
}
```

### Antigravity (Google)

Settings → MCP Servers, veya `~/.antigravity/mcp_settings.json`:

```json
{
  "mcpServers": {
    "fonlar": {
      "command": "uv",
      "args": ["--directory", "/MUTLAK/PATH/fonlar-mcp", "run", "fonlar-mcp"]
    }
  }
}
```

### Zed

`~/.config/zed/settings.json` içinde `context_servers` bloğu:

```json
{
  "context_servers": {
    "fonlar": {
      "command": {
        "path": "uv",
        "args": ["--directory", "/MUTLAK/PATH/fonlar-mcp", "run", "fonlar-mcp"]
      }
    }
  }
}
```

> `uv` yoksa alternatif olarak doğrudan Python kullanılabilir:
> `"command": "python3", "args": ["-m", "fonlar_mcp.server"], "env": {"PYTHONPATH": "/MUTLAK/PATH/fonlar-mcp/src"}`

## Test

MCP Inspector ile araçları manuel deneyebilirsin:

```bash
cd fonlar-mcp
npx @modelcontextprotocol/inspector uv run fonlar-mcp
```

Tarayıcıda açılan UI'dan tool'ları çağır, JSON çıktıyı gör.

## Periyod Kodları

`get_fon_fiyat_gecmisi` ve `karsilastir_fonlar` aşağıdaki periyodları kabul eder:

`hafta` · `1ay` · `3ay` · `6ay` · `1yil` · `3yil` · `5yil`

## Önemli Uyarı

Bu araç **bilgilendirme amaçlıdır**. TEFAS verilerini doğrudan iletir, **yatırım tavsiyesi değildir**. Yatırım kararlarınız size aittir.

## Lisans

MIT — bkz. [LICENSE](LICENSE).

## Veri Kaynağı

Tüm veriler [tefas.gov.tr](https://www.tefas.gov.tr) public API'sinden alınır.