turkiye-mcp
An MCP server that gives your AI agent 17 Türkiye-specific tools covering finance, disaster data, calendars, geography, validation, weather, and Turkish text — all key-free.
Currency & finance: fetch official TCMB exchange rates for any date since 1996 and convert between TRY and ~22 currencies (or cross rates) using buying/selling/banknote rates.
Earthquakes: get recent quakes from AFAD or Kandilli, filtered by hours, magnitude, province, and result limit.
Holidays & business days: list official public holidays (2024–2035, incl. Ramazan/Kurban Bayramı and half-day eves), check if a date is a holiday/weekend/business day, and add or count Turkish business days.
Geography: list all 81 provinces with plate codes, look up a province's districts, or find which province a district belongs to.
Validators: verify T.C. Kimlik No (TCKN), Vergi Kimlik No (VKN), and Turkish IBANs (with bank identification) — fully offline, nothing is sent anywhere.
Prayer times & weather: get Diyanet-method prayer times and current/up-to-7-day weather forecasts for a province or district.
Turkish text utilities: apply correct Turkish upper/lower/title casing, ASCII transliteration, and URL slugs; write amounts in Turkish words (yazıyla) for invoices and cheques.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@turkiye-mcp Is 29 October 2025 a public holiday or a working day in Türkiye?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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,
npxinstalls straight from this GitHub repo (github:celaldrg/turkiye-mcp). After the npm release the arg becomes justturkiye-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-mcpFrom source
git clone https://github.com/celaldrg/turkiye-mcp && cd turkiye-mcp
npm install && npm run build
node dist/index.js # speaks MCP over stdioTools
Tool | What it does | Source | Offline |
| Official TCMB rates (forex/banknote buy/sell), latest or any date since 1996; weekends fall back to the previous bulletin | ||
| Convert between TRY and ~22 currencies (or cross rates) at TCMB rates for a date | TCMB | |
| Latest earthquakes, filter by hours, magnitude, province; UTC and Türkiye time | ||
| All official holidays for 2024-2035 incl. Ramazan/Kurban Bayramı and half-day eves | Law 2429 + Diyanet tables | ✅ |
| Is a date a weekend, holiday, half day or business day? | same | ✅ |
| Date ± N Turkish business days | same | ✅ |
| Business days between two dates | same | ✅ |
| 81 provinces with plate codes | turkey-neighbourhoods (MIT) | ✅ |
| Province by name (any casing/diacritics) or plate, with its districts | same | ✅ |
| Which province(s) a district belongs to (e.g. Gölbaşı → Ankara, Adıyaman) | same | ✅ |
| T.C. Kimlik No checksum | algorithm | ✅ |
| Vergi Kimlik No checksum (10-digit; 11-digit checked as TCKN) | algorithm | ✅ |
| Turkish IBAN mod-97 check + bank name | TCMB EFT participant list | ✅ |
| Imsak, güneş, öğle, ikindi, akşam, yatsı for a province/district | Aladhan (Diyanet method) | |
| Current weather + up to 7-day forecast for a province/district | ||
| Turkish-correct upper/lower/title case, ASCII transliteration, slugs | built-in | ✅ |
| 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 | Indicative rates, published around 15:30 Türkiye time on business days. Not for trading. |
Earthquakes | AFAD event API; Kandilli | 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 stdioPull requests are welcome, especially new public, key-free Türkiye data sources.
Related projects
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 toolsadd_business_daysAdd business daysARead-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)ARead-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?ARead-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 ratesARead-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 daysARead-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 districtARead-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 ratesARead-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)ARead-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 detailsARead-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ürkiyeARead-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ürkiyeARead-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 provinceARead-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 provincesARead-onlyIdempotent
All 81 provinces (il) of Türkiye with plate codes and district counts. Works offline.
Inputs: no named parameters.
turkish_textTurkish-aware text transformsARead-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 IBANARead-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 NoARead-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 NoARead-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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
500+ deterministic tools for AI agents: math, conversion, validation, hashing, encoding, date/time.
Utility tools for AI agents: hashing, text stats, validation, DNS, currency, GEO audits.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
Utility data for AI agents: IBAN, EU holidays, VAT rates, time zones, ECB FX. Pay per call.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables querying Turkish economic data (inflation, FX rates, policy rates, etc.) from TCMB EVDS via curated tools, preventing LLM hallucination.6MIT
- AlicenseAqualityBmaintenanceEnables 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.44109 npm1MIT
- AlicenseAqualityBmaintenanceEnables 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.111MIT
- AlicenseAqualityCmaintenanceEnables 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.4MIT