Skip to main content
Glama

turkiye-mcp 🇹🇷

Give your AI agent Türkiye-specific knowledge it can't guess: official TCMB exchange rates, live earthquakes, the real holiday calendar, business-day math, IBAN/TCKN/VKN checks, provinces & districts, prayer times, weather and correct Turkish text handling.

An MCP server for Claude Desktop, Cursor, VS Code and any other MCP client. No API keys, no sign-up: every tool uses free public data or runs fully offline.

CI License: MIT Release Node >= 20 17 tools

LLMs routinely get these wrong: "What is the USD/TRY rate the central bank published today?", "Is 28 October a working day?", "Which bank is this IBAN?", "istanbul.toUpperCase()" (it's İSTANBUL, not ISTANBUL). This server gives them the right answer, with the source.

Why this one

  • Zero config. No keys, no accounts, no env vars. 12 of 17 tools work offline.

  • Official sources. Rates from TCMB, earthquakes from AFAD and Kandilli, religious holiday dates from Diyanet's own published tables (not an approximate Hijri calculation).

  • Business-day aware. Knows half-day eves (arife), 3-day Ramazan and 4-day Kurban Bayramı, so deadlines like "10 business days from today" come out right.

  • English-first, Turkish-correct. English tool descriptions and output for global agents, with correct Turkish casing, district names and "yazıyla" amounts.

  • Tested. Unit tests on real captured data plus a weekly live check against every upstream API.

Related MCP server: mcp-turkiye

Install

Note: the npm package is not published yet. Until it is, npx installs straight from this GitHub repo (github:celaldrg/turkiye-mcp). After the npm release the arg becomes just turkiye-mcp.

Requires Node.js 20 or newer.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "turkiye": {
      "command": "npx",
      "args": ["-y", "github:celaldrg/turkiye-mcp"]
    }
  }
}

Cursor

Add to Cursor (one click), or add to ~/.cursor/mcp.json / .cursor/mcp.json:

{
  "mcpServers": {
    "turkiye": { "command": "npx", "args": ["-y", "github:celaldrg/turkiye-mcp"] }
  }
}

VS Code (Copilot agent mode)

code --add-mcp '{"name":"turkiye","command":"npx","args":["-y","github:celaldrg/turkiye-mcp"]}'

or .vscode/mcp.json:

{
  "servers": {
    "turkiye": { "type": "stdio", "command": "npx", "args": ["-y", "github:celaldrg/turkiye-mcp"] }
  }
}

Claude Code

claude mcp add turkiye -- npx -y github:celaldrg/turkiye-mcp

From source

git clone https://github.com/celaldrg/turkiye-mcp && cd turkiye-mcp
npm install && npm run build
node dist/index.js   # speaks MCP over stdio

Tools

Tool

What it does

Source

Offline

get_exchange_rates

Official TCMB rates (forex/banknote buy/sell), latest or any date since 1996; weekends fall back to the previous bulletin

TCMB

convert_currency

Convert between TRY and ~22 currencies (or cross rates) at TCMB rates for a date

TCMB

get_recent_earthquakes

Latest earthquakes, filter by hours, magnitude, province; UTC and Türkiye time

AFAD, Kandilli

get_public_holidays

All official holidays for 2024-2035 incl. Ramazan/Kurban Bayramı and half-day eves

Law 2429 + Diyanet tables

✅

check_date

Is a date a weekend, holiday, half day or business day?

same

✅

add_business_days

Date ± N Turkish business days

same

✅

count_business_days

Business days between two dates

same

✅

list_provinces

81 provinces with plate codes

turkey-neighbourhoods (MIT)

✅

get_province

Province by name (any casing/diacritics) or plate, with its districts

same

✅

find_district

Which province(s) a district belongs to (e.g. Gölbaşı → Ankara, Adıyaman)

same

✅

validate_tckn

T.C. Kimlik No checksum

algorithm

✅

validate_vkn

Vergi Kimlik No checksum (10-digit; 11-digit checked as TCKN)

algorithm

✅

validate_iban

Turkish IBAN mod-97 check + bank name

TCMB EFT participant list

✅

get_prayer_times

Imsak, güneş, öğle, ikindi, akşam, yatsı for a province/district

Aladhan (Diyanet method)

get_weather

Current weather + up to 7-day forecast for a province/district

Open-Meteo

turkish_text

Turkish-correct upper/lower/title case, ASCII transliteration, slugs

built-in

✅

amount_to_words

Amount in Turkish words for invoices/cheques ("yazıyla")

built-in

✅

All tools are read-only. Validators never send the numbers anywhere.

Example prompts

  • "How much is 2,500 EUR in lira at today's TCMB selling rate? And what was it on 1 January 2025?"

  • "Were there any earthquakes above magnitude 4 in Türkiye in the last 48 hours? Which provinces?"

  • "Our invoice is due 15 business days after 20 May 2026. What's the date in Türkiye?"

  • "Which days are holidays in 2027, and which ones make a long weekend?"

  • "Check this IBAN and tell me the bank: TR36 0001 0001 2345 6789 0123 45"

  • "Write 18.750,40 TL in words for the invoice."

  • "What time is iftar (akşam) in Kadıköy, İstanbul tomorrow?"

  • "Convert this list of city names to proper Turkish uppercase for the shipping labels."

Demo

Real output from node scripts/demo.mjs (MCP client SDK → this server over stdio), captured on 26 October 2026. Full, unedited transcript: docs/demo-transcript.md.

# 17 tools: get_exchange_rates, convert_currency, get_recent_earthquakes, get_public_holidays, check_date, add_business_days, count_business_days, list_provinces, get_province, find_district, validate_tckn, validate_vkn, validate_iban, get_prayer_times, get_weather, turkish_text, amount_to_words

> convert_currency {"amount":1000,"from":"USD","to":"TRY"}
{
  "amount": 1000,
  "from": "USD",
  "to": "TRY",
  "result": 49762.7,
  "rate": 49.7627,
  "rate_type": "forex_selling",
  "bulletin_date": "2026-10-26",
  "source_url": "https://www.tcmb.gov.tr/kurlar/today.xml"
}

> add_business_days {"start":"2026-10-27","days":3}
{
  "start": "2026-10-27",
  "days": 3,
  "result": "2026-11-02",
  "result_weekday": "Monday"
}

> validate_iban {"iban":"TR36 0001 0001 2345 6789 0123 45"}
{
  "input": "TR36 0001 0001 2345 6789 0123 45",
  "valid": true,
  "formatted": "TR36 0001 0001 2345 6789 0123 45",
  "bank_code": "00010",
  "bank": "T.C. Ziraat Bankası A.Ş.",
  "reserved_digit": "0",
  "account_part": "0123456789012345"
}

> amount_to_words {"amount":1250.5}
{
  "amount": "1250.50",
  "currency": "TRY",
  "text": "Bin İki Yüz Elli Türk Lirası Elli Kuruş",
  "compact": "BinİkiYüzElliTL,ElliKr",
  "upper": "BİN İKİ YÜZ ELLİ TÜRK LİRASI ELLİ KURUŞ"
}

> turkish_text {"text":"istanbul ılık","operation":"upper"}
{
  "operation": "upper",
  "input": "istanbul ılık",
  "output": "İSTANBUL ILIK"
}

Why 2 November: 28 October is a half day, which still counts as a working day. 29 October is Republic Day and 31 October to 1 November is a weekend, so the three business days are 28 Oct, 30 Oct and 2 Nov.

Data sources and accuracy

Data

Source

Notes

Exchange rates

TCMB today.xml and daily archive

Indicative rates, published around 15:30 Türkiye time on business days. Not for trading.

Earthquakes

AFAD event API; Kandilli lst0.asp

Preliminary automatic solutions can be revised by the agencies.

Religious holidays

Diyanet "Resmi Tatiller" tables 2024-2035

Bundled; if the government adds a bridge day (idari izin) it is not included.

Provinces/districts

turkey-neighbourhoods v4.0.3 (MIT)

81 provinces, 973 districts. See THIRD_PARTY_NOTICES.md.

Banks

TCMB EFT/FAST participant list (2026)

Used only to name the bank of an IBAN.

Prayer times

Aladhan API, method 13 (Diyanet)

Computed; can differ from Diyanet's official times by a minute or two.

Weather

Open-Meteo (CC BY 4.0)

Free for non-commercial use; see Open-Meteo terms for commercial use.

Checksum validators only confirm that a number is well-formed. They do not prove that an ID, tax number or account exists.

Development

npm install
npm run build
npm test                 # unit tests (offline, uses real captured fixtures)
npm run test:live        # hits the real APIs
node scripts/demo.mjs    # end-to-end over stdio

Pull requests are welcome, especially new public, key-free Türkiye data sources.

  • BerkantACUN/mcp-turkiye: a broad, Turkish-first MCP server with many more endpoints. If you want maximum coverage, look there; turkiye-mcp focuses on a small, tested, key-free, English-first core.

  • saidsurucu/borsa-mcp: Borsa İstanbul and fund data.

  • awesome-turkiye-dev: a curated list of Turkish developer resources.

License

MIT © Celalettin Durğaç. Not affiliated with TCMB, AFAD, Kandilli, Diyanet or any other source listed above.

Available Tools

17 tools
add_business_daysAdd business daysA
Read-onlyIdempotent

Add (or subtract, with a negative number) N Turkish business days to a date, skipping weekends and full-day public holidays. Useful for legal, payment and delivery deadlines.

Inputs: days (required), start (required).

amount_to_wordsAmount in Turkish words (yazıyla)A
Read-onlyIdempotent

Write a number or money amount in Turkish words, as required on invoices, cheques and contracts, e.g. 1250.50 -> "Bin İki Yüz Elli Türk Lirası Elli Kuruş".

Inputs: amount (required), currency.

check_dateIs it a holiday / business day?A
Read-onlyIdempotent

Tells whether a date in Türkiye is a weekend, a public holiday (full or half day) or a business day. Works offline.

Inputs: date.

convert_currencyConvert currency at TCMB ratesA
Read-only

Convert an amount between TRY and any currency in the TCMB bulletin (or between two foreign currencies via TRY) using official TCMB rates for a date.

Inputs: to (required), from (required), amount (required), date, +1 more.

count_business_daysCount business daysA
Read-onlyIdempotent

Count Turkish business days after start up to and including end (weekends and full-day public holidays excluded).

Inputs: end (required), start (required).

find_districtFind a districtA
Read-onlyIdempotent

Find which province a district (ilçe) belongs to. Handles names that exist in several provinces. Works offline.

Inputs: name (required).

get_exchange_ratesTCMB exchange ratesA
Read-only

Official indicative exchange rates (TRY per unit) from the Central Bank of the Republic of Türkiye (TCMB). Latest bulletin by default, or any past date since 1996 (weekends/holidays fall back to the previous bulletin).

Inputs: date, currencies.

get_prayer_timesPrayer times (Diyanet method)A
Read-only

Daily prayer times (imsak, güneş, öğle, ikindi, akşam, yatsı) for a province or district, computed with the Diyanet method via the free Aladhan API.

Inputs: province (required), date, district.

get_provinceProvince detailsA
Read-onlyIdempotent

Look up a province by name (any casing, with or without Turkish characters) or plate code, and get its districts (ilçe). Works offline.

Inputs: query (required).

get_public_holidaysPublic holidays of TürkiyeA
Read-onlyIdempotent

Official public holidays for a year (2024-2035), including Ramazan/Kurban Bayramı dates from Diyanet's official tables and half-day eves (arife). Works offline.

Inputs: year.

get_recent_earthquakesRecent earthquakes in and around TürkiyeA
Read-only

Latest earthquakes from AFAD (Disaster and Emergency Management Authority) or Kandilli Observatory (Boğaziçi University). Times are returned in UTC and Türkiye local time.

Inputs: hours, limit, source, province, +1 more.

get_weatherWeather for a Turkish provinceA
Read-only

Current weather and a short daily forecast for a province or district, from Open-Meteo (free, no key).

Inputs: province (required), days, district.

list_provincesList the 81 provincesA
Read-onlyIdempotent

All 81 provinces (il) of Türkiye with plate codes and district counts. Works offline.

Inputs: no named parameters.

turkish_textTurkish-aware text transformsA
Read-onlyIdempotent

Correct Turkish upper/lower/title case (i/İ, ı/I), ASCII transliteration and URL slugs. LLMs often get the dotted/dotless i wrong; use this instead.

Inputs: text (required), operation (required).

validate_ibanValidate Turkish IBANA
Read-onlyIdempotent

Validate a Turkish IBAN (mod-97) and identify the bank from the TCMB participant list. Offline.

Inputs: iban (required).

validate_tcknValidate T.C. Kimlik NoA
Read-onlyIdempotent

Check the checksum of a Turkish national ID number (T.C. Kimlik No). Offline; the number is never sent anywhere.

Inputs: tckn (required).

validate_vknValidate Vergi Kimlik NoA
Read-onlyIdempotent

Check the checksum of a Turkish tax ID (10-digit VKN; 11-digit input is checked as a TCKN). Offline.

Inputs: vkn (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose across finance, disaster data, holidays, geography, validation, prayer, weather, and text utilities. The closest pairs (get_exchange_rates vs convert_currency, check_date vs business-day tools, list_provinces vs get_province vs find_district) are still easily distinguished by their descriptions.

    Naming Consistency4/5

    Most tools follow a predictable snake_case verb_noun pattern (get_exchange_rates, validate_iban, add_business_days, etc.). Two tools, turkish_text and amount_to_words, use noun phrases instead, which is a minor but notable deviation.

    Tool Count4/5

    At 17 tools, the set is slightly above the typical 3-15 sweet spot, but the server explicitly covers many Türkiye-specific domains and each tool earns its place. It does not feel bloated or redundant despite being a bit heavy.

    Completeness4/5

    The surface covers core operations well: exchange rates and conversion, earthquake retrieval, holiday/business-day calculations, province/district lookup, TCKN/VKN/IBAN validation, prayer times, weather, and Turkish text formatting. Minor gaps exist, such as postal-code lookup or deeper earthquake/weather detail, but agents can work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables querying Turkish economic data (inflation, FX rates, policy rates, etc.) from TCMB EVDS via curated tools, preventing LLM hallucination.
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to query Turkey's public data, including central-bank FX rates, earthquake catalog, weather forecasts, public holidays, and offline validation of Turkish ID, tax, and IBAN numbers, with sourced and timestamped responses.
      44
      109 npm
      1
      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
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to retrieve official Turkish central bank exchange rates, historical currency series, and perform currency conversions with correct handling of weekends, holidays, and daily publication timing. It returns structured outputs and clearly indicates the bulletin date for each rate.
      4
      MIT