Skip to main content
Glama
tcmb-mcp

tcmb-mcp

by efeozkanw

tcmb-mcp

npm CI License: MIT

An MCP server for the daily exchange rates of the Central Bank of the Republic of Türkiye (TCMB).

It reads the official XML bulletins straight from tcmb.gov.tr, needs no API key, and handles the parts that usually go wrong: weekends and public holidays, the 15:30 publication time, currencies quoted per 100 units, missing rates, and the rate Turkish tax practice expects on a foreign currency invoice.

Türkçe

Install

Requires Node.js 22.12 or later.

Claude Code

claude mcp add tcmb -- npx -y tcmb-mcp

Add --scope user to make it available in every project.

Claude Desktop, Cursor, Windsurf

Add this to claude_desktop_config.json, ~/.cursor/mcp.json or the equivalent file:

{
  "mcpServers": {
    "tcmb": {
      "command": "npx",
      "args": ["-y", "tcmb-mcp"]
    }
  }
}

VS Code

{
  "servers": {
    "tcmb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tcmb-mcp"]
    }
  }
}

Related MCP server: TCMB MCP

Tools

Tool

What it does

tcmb_get_rates

Rates from the latest bulletin or a given date, for all currencies or a selection. response_format: "detailed" adds names and banknote rates.

tcmb_convert

Converts an amount between TRY and a foreign currency, or between two foreign currencies through their TRY rates.

tcmb_invoice_rate

The rate for a foreign currency invoice: the last bulletin before the invoice date, forex buying by default. Optionally returns the TRY amount rounded to kuruş.

tcmb_get_history

One currency over a date range, daily, weekly or monthly, with first, last, min, max and percentage change.

tcmb_list_currencies

Currencies in a bulletin, their Turkish and English names, quoted unit and which rate types exist.

All tools are read-only and return structured output with a JSON schema.

Things you can ask once it is installed:

  • What is the euro selling rate today?

  • I am issuing a 3,400 USD invoice dated 2 January 2026. What lira amount goes on it?

  • How did the dollar move against the lira month by month in 2025?

  • Convert 250 GBP to EUR using the rates of 15 March 2024.

How dates are handled

  • TCMB announces one bulletin per business day at 15:30 Istanbul time. Until then the most recent bulletin is the previous business day's.

  • There is no bulletin on weekends, public holidays or the half day before a religious holiday. Asking for such a date returns the closest earlier bulletin. Every response carries requested_date, bulletin_date and fallback_reason (weekend, holiday or not_published_yet) so nothing is silently substituted.

  • tcmb_invoice_rate always uses the bulletin before the invoice date, which is the one published in the Official Gazette on that date. An invoice dated Monday therefore uses Friday's rate.

  • Rates are lira per one unit. Currencies TCMB quotes per 100 units, such as JPY, are divided.

  • Bulletins before 2005 are in old lira and are converted to the current lira (1 TRY = 1,000,000 TRL).

  • The archive goes back to 16 April 1996. The set of currencies changes over the years, so codes are read from each bulletin rather than hard-coded.

Past bulletins never change, so they are kept in memory for the life of the process. The current bulletin is refreshed every ten minutes. Requests time out after ten seconds and server errors are retried twice.

Library use

The client behind the server is exported as well:

import { TcmbClient } from 'tcmb-mcp';

const tcmb = new TcmbClient();
const { bulletin, fallbackReason } = await tcmb.resolve('2026-10-29');

Development

npm ci
npm test
npm run test:live
npm run inspect

npm test runs against recorded bulletins in test/fixtures and does not touch the network. npm run test:live checks the real TCMB endpoints. npm run inspect opens the server in the MCP Inspector.

Data and disclaimer

The data comes from the indicative exchange rates published by TCMB at tcmb.gov.tr. This project is not affiliated with TCMB. The rates are indicative; check them against the official source before using them in accounting or tax filings.

For macroeconomic series such as inflation, interest rates and reserves, use TCMB's own EVDS MCP server.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides access to currency exchange rates and conversion tools using the Frankfurter API, including latest rates, historical data, and time series from sources like the European Central Bank.
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Provides access to Turkish Central Bank (TCMB) exchange rates with current and historical data since 1996, currency conversion, rate history statistics, and multi-currency comparisons with smart caching.
      6
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables real-time currency exchange rate retrieval and conversion for over 200 currencies. Supports operations like getting rates, converting amounts, and comparing currencies through natural language.
      -
    • 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