TCMB MCP

Production-ready MCP (Model Context Protocol) server for Turkish Central Bank (TCMB) exchange rates.

Features

• Current Rates: Get today's exchange rates from TCMB
• Historical Rates: Query rates for any date since 1996
• Currency Conversion: Convert between any currencies (including TRY)
• Rate History: Get rate history with statistics (min, max, avg, change %)
• Multi-Currency Comparison: Compare multiple currencies over time
• Smart Caching: SQLite-based cache with configurable TTL
• Holiday Support: Automatic fallback to previous business day
• Turkish Holidays: Includes all official and religious holidays

Installation

Using Smithery (Recommended)

Install directly via Smithery:

npx -y @smithery/cli install @ofurkanuygur/tcmb_mcp --client claude

Using uv (Local Development)

git clone https://github.com/ofurkanuygur/tcmb_mcp.git
cd tcmb_mcp
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

Using pip

pip install tcmb-mcp

Usage

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "tcmb": {
      "command": "python",
      "args": ["-m", "tcmb_mcp"],
      "env": {
        "TCMB_CACHE_ENABLED": "true",
        "TCMB_DEBUG": "false"
      }
    }
  }
}

Running Manually

# stdio mode (default, for Claude Desktop)
python -m tcmb_mcp

# HTTP mode (for Smithery deployment)
MCP_TRANSPORT=http python -m tcmb_mcp

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python -m tcmb_mcp

Available Tools

1. tcmb_get_current_rates

Get current exchange rates from TCMB.

Dolar ve Euro kurunu göster
→ tcmb_get_current_rates(currencies=["USD", "EUR"])

2. tcmb_get_historical_rates

Get exchange rates for a specific date.

15 Ocak 2024 kurlarını getir
→ tcmb_get_historical_rates(date="2024-01-15")

3. tcmb_list_currencies

List all available currencies.

Hangi para birimleri var?
→ tcmb_list_currencies()

4. tcmb_convert_currency

Convert between currencies.

1000 Dolar kaç TL?
→ tcmb_convert_currency(amount=1000, from_currency="USD", to_currency="TRY")

5. tcmb_get_rate_history

Get rate history with statistics.

Son 30 günde Dolar nasıl değişti?
→ tcmb_get_rate_history(currency="USD", start_date="2024-11-01", end_date="2024-11-30")

6. tcmb_compare_currencies

Compare multiple currencies.

Dolar, Euro ve Sterlin'i karşılaştır
→ tcmb_compare_currencies(target_currencies=["USD", "EUR", "GBP"])

Configuration

Environment Variables

Variable	Default	Description
TCMB_CACHE_ENABLED	true	Enable SQLite caching
TCMB_CACHE_DB_PATH	~/.cache/tcmb-mcp/tcmb_cache.db	Cache database path
TCMB_CACHE_TTL_TODAY	3600	Cache TTL for today (seconds)
TCMB_CACHE_TTL_HISTORICAL	31536000	Cache TTL for historical (seconds)
TCMB_TIMEOUT	10	API timeout (seconds)
TCMB_MAX_RETRIES	3	Maximum retry attempts
TCMB_DEBUG	false	Enable debug logging
TCMB_LOG_LEVEL	INFO	Log level
MCP_TRANSPORT	stdio	Transport mode (stdio or http)
PORT	8080	HTTP server port (when using HTTP transport)

Development

Setup

git clone https://github.com/ofurkanuygur/tcmb_mcp.git
cd tcmb_mcp
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Running Tests

# All tests
pytest

# With coverage
pytest --cov=src/tcmb_mcp --cov-report=term-missing

# Unit tests only
pytest tests/unit/

Code Quality

# Linting
ruff check src/

# Type checking
mypy src/

Local HTTP Server Testing

# Start server in HTTP mode
MCP_TRANSPORT=http python -m tcmb_mcp

# Test with Smithery playground
npx -y @smithery/cli playground --port 8080

Docker

Build

docker build -t tcmb-mcp .

Run

docker run -p 8080:8080 tcmb-mcp

API Reference

TCMB URL Format

• Today's rates: https://www.tcmb.gov.tr/kurlar/today.xml
• Historical: https://www.tcmb.gov.tr/kurlar/YYYYMM/DDMMYYYY.xml
  • Example: January 15, 2024 → /kurlar/202401/15012024.xml

Rate Types

Type	Turkish	Description
forex_buying	Döviz Alış	Electronic transfer buying rate
forex_selling	Döviz Satış	Electronic transfer selling rate
banknote_buying	Efektif Alış	Cash buying rate
banknote_selling	Efektif Satış	Cash selling rate

Author

Oktay Furkan Uygur

• GitHub: @ofurkanuygur

Acknowledgments

• TCMB for providing public exchange rate data
• Anthropic for the MCP protocol
• Smithery for MCP server hosting