Skip to main content
Glama

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

Related MCP server: Wise Currency Converter MCP Server

Installation

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

Acknowledgments

  • TCMB for providing public exchange rate data

  • Anthropic for the MCP protocol

  • Smithery for MCP server hosting

Available Tools

6 tools
tcmb_compare_currenciesC
Read-onlyIdempotent

Birden fazla para birimini karşılaştırır.

Inputs: target_currencies (required), base_currency, days.

tcmb_convert_currencyB
Read-onlyIdempotent

Para birimlerini çevirir (TRY dahil).

Inputs: amount (required), from_currency (required), to_currency (required), rate_type.

tcmb_get_current_ratesB
Read-onlyIdempotent

Güncel döviz kurlarını TCMB'den getirir.

Inputs: currencies.

tcmb_get_historical_ratesB
Read-onlyIdempotent

Belirli bir tarih için geçmiş döviz kurlarını getirir.

Inputs: date (required), currencies.

tcmb_get_rate_historyB
Read-onlyIdempotent

Para birimi kur geçmişi ve istatistikleri.

Inputs: currency (required), start_date (required), end_date (required), rate_type.

tcmb_list_currenciesB
Read-onlyIdempotent

TCMB'de mevcut tüm para birimlerini listeler.

Inputs: include_rates.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as comparing currencies, converting, getting current rates, historical rates, rate history, and listing currencies. However, 'tcmb_get_historical_rates' and 'tcmb_get_rate_history' could be slightly confusing as both involve historical data, though their descriptions suggest different focuses (specific date vs. history and statistics).

    Naming Consistency5/5

    All tool names follow a consistent 'tcmb_verb_noun' pattern with snake_case, using clear verbs like 'compare', 'convert', 'get', and 'list'. This predictability makes it easy for agents to understand and select tools.

    Tool Count5/5

    With 6 tools, the server is well-scoped for currency and exchange rate operations, covering key functions like conversion, rate retrieval, and historical data without being overwhelming or too sparse.

    Completeness4/5

    The tool set provides comprehensive coverage for currency exchange rate tasks, including listing, current and historical rates, conversion, and comparison. A minor gap might be the lack of tools for more advanced analytics or alerts, but core operations are well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time and historical foreign exchange rates for 31+ currencies, enabling currency conversion, historical rate lookups, and time series analysis using data from the Frankfurter API.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Fetches official currency exchange rates from the National Bank of Kazakhstan, supports conversion and rate dynamics tracking.
      5
      15 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM clients to retrieve official Turkish central-bank exchange rates, MPC (PPK) decisions, Inflation Reports, Financial Stability Reports, and market-participant surveys, with page- or bulletin-level citations and sentence-level comparisons of policy statements. It works without any API key for FX data and documents, while an optional free EVDS key unlocks the full statistical catalogue for policy rates, inflation, and reserves.
      11
      1
      MIT