tefas-fund-comparator

MCP (Model Context Protocol) sunucusu: TEFAS fonlarını listeleme, karşılaştırma, getiri/performans analizi ve portföy dağılımı inceleme.

Sunucu adı: tefas-fund-comparator

Özellikler

Tool	Açıklama
list_funds	Fon tipi + tarih aralığı + kod/isim filtresi ile fon listesi
get_fund_details	Fiyat geçmişi, özet metrikler, portföy dağılımı
compare_funds	Çoklu fon: getiri, volatilite, Sharpe, max drawdown, AUM
get_portfolio_breakdown	Varlık dağılımı (hisse, repo, eurobond, …)
get_historical_returns	RB / SB / MB bazlı TEFAS getiri tabloları
analyze_performance	Risk/getiri istatistikleri (pandas)

• stdio + Streamable HTTP transport
• pytefas: otomatik chunking + rate-limit retry
• tefasfon: RB/SB/MB getiri tabloları
• Çıktı: markdown tablo veya JSON

Kurulum

Gereksinimler

• Python 3.10+
• İnternet erişimi (TEFAS API)

pip

cd TEFAS-MCP
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
# source .venv/bin/activate

pip install -e .
# veya
pip install -r requirements.txt
pip install -e .

uv

cd TEFAS-MCP
uv venv
uv pip install -e .

Çalıştırma

stdio (Claude Code / Cline / Cursor — varsayılan)

python -m tefas_mcp.server
# veya
tefas-fund-comparator

Streamable HTTP

python -m tefas_mcp.server --transport http --host 127.0.0.1 --port 8000
# Endpoint: http://127.0.0.1:8000/mcp
# Health:   http://127.0.0.1:8000/health

Yardım

python -m tefas_mcp.server --help

Docker (yerel)

# Image build + run (port 8000)
docker compose up --build

# veya
docker build -t tefas-fund-comparator .
docker run --rm -p 8000:8000 -e PORT=8000 tefas-fund-comparator

Kontrol:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/

Render.com (Docker Web Service)

Hazır dosyalar: Dockerfile, render.yaml, .dockerignore.

A) Blueprint (önerilen)

1. Kodu GitHub’a push edin.
2. Render Dashboard → New → Blueprint.
3. Repo’yu seçin; render.yaml otomatik okunur.
4. Deploy sonrası URL örneği: https://tefas-fund-comparator.onrender.com
5. MCP endpoint: https://tefas-fund-comparator.onrender.com/mcp
   Health: https://tefas-fund-comparator.onrender.com/health

B) Manuel Web Service

1. New → Web Service → repo bağla
2. Runtime: Docker
3. Dockerfile path: ./Dockerfile
4. Health Check Path: /health
5. Env (opsiyonel; Dockerfile varsayılanları yeter):

Key	Value
MCP_TRANSPORT	http
HOST	0.0.0.0
MCP_PATH	/mcp
LOG_LEVEL	INFO

PORT Render tarafından otomatik enjekte edilir; elle yazmayın.

Claude / Cline ile Render URL

Claude genelde uzak HTTP MCP’ye doğrudan bağlanmaz; mcp-remote kullanın (examples/mcp_config.render.json):

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SERVICE.onrender.com/mcp"
      ]
    }
  }
}

YOUR-SERVICE kısmını kendi Render servis adınızla değiştirin.

Render notları

• Free plan idle sonrası uykuya geçer; ilk istek ~30–60 sn sürebilir.
• TEFAS rate-limit nedeniyle uzun analizler yavaş / timeout olabilir; gerekirse plan yükseltin veya timeout’ları artırın.
• Servis herkese açıksa istek koruması (auth, IP allowlist, Cloudflare) eklemeniz önerilir — bu imajda API anahtarı yoktur.

MCP istemci yapılandırması

Aşağıda PYTHON yolunu kendi venv’inize göre düzenleyin.

Claude Code / Claude Desktop (claude_desktop_config.json veya proje .mcp.json)

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "C:\\Users\\kerem\\Documents\\TEFAS-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "C:\\Users\\kerem\\Documents\\TEFAS-MCP"
    }
  }
}

macOS/Linux örneği:

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "/path/to/TEFAS-MCP/.venv/bin/python",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "/path/to/TEFAS-MCP"
    }
  }
}

Global pip install -e . yaptıysanız:

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "tefas-fund-comparator",
      "args": []
    }
  }
}

Cline (VS Code)

Cline → MCP Settings:

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "python",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "C:\\Users\\kerem\\Documents\\TEFAS-MCP",
      "disabled": false
    }
  }
}

HTTP + mcp-remote (isteğe bağlı)

Önce sunucuyu HTTP modunda başlatın, sonra:

{
  "mcpServers": {
    "tefas-fund-comparator-http": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

uvx (paket yayımlanmışsa)

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "uvx",
      "args": ["tefas-fund-comparator"]
    }
  }
}

Yerel dizinden uv run:

{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\kerem\\Documents\\TEFAS-MCP", "python", "-m", "tefas_mcp.server"]
    }
  }
}

Fon tipleri

Kod	Anlam	tefasfon alias
YAT	Yatırım fonu	SEC
EMK	Emeklilik	PEN
BYF	Borsa yatırım fonu (ETF)	ETF
GYF	Gayrimenkul	RE
GSYF	Girişim sermayesi	VC

Örnek tool çağrıları

Agent / istemci üzerinden (anlamsal örnekler):

list_funds(fund_type="YAT", name_contains="ALTIN", limit=20)

get_fund_details(fund_code="AAL", fund_type="YAT")

compare_funds(
  fund_codes=["AAL", "AAK"],
  start_date="2026-01-01",
  end_date="2026-04-01",
  metrics=["return", "volatility", "sharpe", "max_drawdown"]
)

get_portfolio_breakdown(fund_code="AAL")

get_historical_returns(fund_type="YAT", basis="RB", limit=25)

analyze_performance(
  fund_codes=["AAL", "AAK"],
  start_date="2025-04-01",
  end_date="2026-04-01",
  risk_free_annual=0.40
)

Rate limit ve süre

TEFAS yaklaşık dakikada 6 istek sınırına yakındır. pytefas uzun aralıkları ~28 günlük parçalara böler:

Aralık	Kabaca süre
1 ay	~10 sn
3 ay	~1 dk
1 yıl	~3 dk

Aynı istekler ~60 sn TTL ile bellekte önbelleğe alınır.

Test

pip install -e ".[dev]"
pytest -q

Ağ gerektiren smoke test (manuel):

python -c "from tefas_mcp.client import get_service; print(get_service().fetch_info('2026-04-20','2026-04-24',kind='YAT',fund_code='AAL').head())"

Proje yapısı

src/tefas_mcp/
  server.py           # FastMCP entrypoint
  client/             # pytefas + tefasfon façade
  tools/              # 6 MCP tools
  analytics/          # Sharpe, vol, max DD
  models/             # enums / validation
  utils/              # dates, formatters, errors

Bağımlılıklar

• fastmcp
• pytefas
• tefasfon
• pandas, pydantic, httpx

Uyarı

Bu araç yatırım tavsiyesi değildir. TEFAS API’si resmi olarak dokümante edilmemiştir; site değişikliklerinde paket güncellemesi gerekebilir. Metrikler eğitim / karşılaştırma amaçlı basitleştirilmiş istatistiklerdir.

Lisans

MIT