TurkishBankMCP
This is a read-only MCP server for Garanti BBVA account and transaction data.
Check Garanti API Store configuration status without exposing credentials.
Test OAuth
client_credentialsauthentication; access tokens are never returned.List accounts and retrieve balances via the Account Information product.
List account transactions for a required account reference and ISO date-time range.
Filter transactions by direction (
A/B), minimum/maximum amount, and paginate results.All tools are read-only, idempotent, and non-destructive.
It cannot send money, initiate payments/EFTs, manage cards, or make purchases.
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., "@TurkishBankMCP What are my current balances and recent transactions?"
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.
TurkishBankMCP
Garanti BBVA API Store ile çalışan, yapay zekâ ajanlarına salt-okunur hesap ve hareket verisi erişimi veren güvenli bir Model Context Protocol (MCP) sunucusu.
TurkishBankMCP, finansal veriyi bir sohbet kutusuna kopyalayan geçici bir script değil; OAuth 2.0, token yaşam döngüsü, hata toleransı ve açık güvenlik sınırları olan küçük ama gerçek bir entegrasyon katmanı.
Şu an Garanti BBVA için hazır. Başka banka kullanıyorsan aynı BankProvider sözleşmesiyle kendi providerını ekleyebilirsin.
Neden güçlü bir portföy projesi?
Gerçek dünya entegrasyonu: Herkesin yaptığı bir CRUD uygulaması yerine OAuth korumalı, hassas veri taşıyan bir banka API’siyle çalışır.
AI ajanları için tasarlandı: Hermes, OpenClaw ve diğer MCP istemcileri standart araç çağrılarıyla hesap bilgisi ve hareketleri analiz edebilir.
Arada aggregator yok: Kobaküs veya başka bir aracı yerine doğrudan Garanti API Store’a bağlanır; mimari ve veri akışı okunabilir kalır.
Güvenlik varsayılanı: Para gönderme, ödeme, EFT, kart yönetimi veya satın alma araçları yoktur. Endpoint denylist’i ödeme/transfer sınıfı URL’leri reddeder.
Üretim kaygısı taşıyor: Tokenlar MCP yanıtlarına girmez; 401 sonrası tek yenileme, 429/geçici 5xx için sınırlı retry, timeout ve secret-file desteği vardır.
Denetlenebilir: TypeScript ile yazılmıştır, MCP tool şemaları açıktır, test/typecheck/build kontrolleri projede bulunur ve lisansı MIT’tir.
Bu repo Garanti BBVA’nın resmi ürünü olduğunu iddia etmez. Canlı erişim, Garanti Developer Portal’daki uygulama ve API onayına bağlıdır; proje bu resmi erişimi güvenli, agent-uyumlu ve salt-okunur biçimde kullanır.
Related MCP server: saldo-mcp
Ne yapar, ne yapmaz?
Hermes, OpenClaw veya başka bir MCP istemcisi hesap bilgini ve hesap hareketlerini okuyabilir; örneğin günlük nakit akışını özetleyebilir, gelen/giden tutarları ayırabilir ve tekrarlayan harcamaları inceleyebilir.
Para gönderme, ödeme başlatma, EFT, kart yönetme veya satın alma yapmaz.
Kodda bu işlemlere ait tool da yoktur.
Garanti tarafında ne lazım
Garanti Developer Portal hesabı aç
Manage -> Applications -> Add Application yolundan yeni app oluştur
API Management kısmında sadece şunları seç
Account Information
Account Transactions
Başka ödeme transfer tahsilat API'si ekleme
Authentication kısmında callback URL HTTPS ve dışarıdan erişilebilir olmalı
Scope alanına OOB
Type alanına Confidential
Submit edince Client ID ve Client Secret geliyor
App önce Pending Approval olur
Garanti onayladıktan sonra canlı isteklere geçebilirsin
OAuth tarafını TurkishBankMCP kendi yapıyor
Garanti'nin resmi token endpointi hazır tanımlı
https://apis.garantibbva.com.tr/auth/oauth/v2/tokenclient_credentials ile token alıyor
Token hiçbir MCP cevabında gösterilmiyor
Neden endpointleri env içine yazıyoruz
Garanti public sayfasında Account Information ve Account Transactions ürünlerinin varlığını gösteriyor
Ama bu ürünlerin gerçek endpoint path request method ve body şeması login arkasındaki API ekranında görünüyor
O yüzden burada path uydurmuyoruz
Portal sana ne gösteriyorsa aynısını .env içine koyuyorsun
Bu daha güvenli ve production için daha doğru
.env
Önce
cp .env.example .envSonra
GARANTI_CLIENT_ID=
GARANTI_CLIENT_SECRET=
GARANTI_REDIRECT_URI=https://senin-domainin.com/callback
GARANTI_ACCOUNT_INFORMATION_URL=
GARANTI_ACCOUNT_INFORMATION_METHOD=
GARANTI_ACCOUNT_INFORMATION_CONTENT_TYPE=application/json
GARANTI_ACCOUNT_INFORMATION_BODY_TEMPLATE=
GARANTI_ACCOUNT_TRANSACTIONS_URL=
GARANTI_ACCOUNT_TRANSACTIONS_METHOD=
GARANTI_ACCOUNT_TRANSACTIONS_CONTENT_TYPE=application/json
GARANTI_ACCOUNT_TRANSACTIONS_BODY_TEMPLATE=Transaction URL veya body içinde şu alanları kullanabilirsin
{{accountRef}}
{{from}}
{{to}}
{{direction}}
{{minAmount}}
{{maxAmount}}
{{page}}
{{pageSize}}Mesela Garanti dokümanı account id ve tarihleri query string içinde istiyorsa URL template kullanırsın
Body içinde istiyorsa body template kullanırsın
Kod GET ve POST destekliyor
JSON ve form-urlencoded body destekliyor
Client Secret dosyada dursun istersen
.env içine secret yazmak zorunda değilsin
GARANTI_CLIENT_SECRET_FILE=.secrets/garanti-client-secretDosya içindeki secret token yenilenirken tekrar okunur
İlk test
Kurulum
git clone git@github.com:OnurByte/TurkishBankMCP.git
cd TurkishBankMCP
npm install
cp .env.example .env
npm run check
npm run buildMCP Inspector aç
npm run inspectİlk önce
bank_provider_statusSonra
bank_test_connectionBu sadece OAuth bağlantısını test eder
Başarılıysa
{
"provider": "garanti-api-store",
"oauth": "ok",
"readOnly": true
}görürsün
Access tokenı göstermez
Sonra
bank_list_accountsve
bank_list_transactionsile gerçek API'yi test edebilirsin
MCP tool'ları
bank_provider_status
bank_test_connection
bank_list_accounts
bank_get_balances
bank_list_transactionsHepsi read-only olarak işaretli
Hermes
Build aldıktan sonra
mcp_servers:
turkish_bank:
command: "node"
args:
- "/absolute/path/to/TurkishBankMCP/dist/index.js"Sonra mesela
Bugünkü hesap hareketlerime bak
ne kadar para geldi ne kadar çıktı söyle
tekrarlayan harcamaları bul
bana kısa bir finans özeti çıkar
hiçbir finansal işlem yapmadiyebilirsin
Şu an Garanti response şeması public dokümanda yayınlanmadığı için MCP bankadan gelen Account Information ve Account Transactions cevabını bozmadan döndürüyor
İlk gerçek response geldiğinde normalizerı o gerçek şemaya göre sabitlemek daha doğru
Güvenlik
Portal app'ine sadece Account Information ve Account Transactions yetkisi ver
Client Secret ve token MCP tool çıktısına girmez
401 gelirse token bir kere otomatik yenilenir
429 ve geçici 5xx hatalarında kontrollü retry var
Endpoint URL'sinde transfer payment EFT tahsilat kredi kart yönetimi gibi ifadeler varsa config güvenlik için reddedilir
TurkishBankMCP içinde ödeme veya transfer tool'u yok
Hermes'e ayrıca sınırsız shell ve filesystem yetkisi verirsen o ayrı güvenlik sınırı
Sıkça sorulan sorular
Bu proje ücretsiz mi
Evet proje tamamen açık kaynak ve ücretsiz
Garanti API Store'un canlı kullanım şartları ise Garanti'nin onayına bağlı
Başka banka kullanıyorum ne yapacağım
Bu sürüm sadece Garanti için hazır
Başka banka kullanıyorsan kendi providerını ekleyebilirsin
Banka şifremi girmem gerekiyor mu
Hayır bu entegrasyon internet bankacılığı şifresiyle çalışmıyor
Developer Portal üzerinden verilen Client ID ve Client Secret kullanılıyor
AI para gönderebilir mi
Bu MCP üzerinden hayır
Ödeme transfer EFT veya kart yönetim tool'u yok
Token Hermes'e gider mi
Hayır
Token sadece provider içinde kullanılıyor
Neden endpoint URL'sini kendim yazıyorum
Çünkü Garanti ürün endpointlerini ve request şemasını portal içindeki API dokümanında gösteriyor
Public sayfada bunların path'i yayınlanmıyor
Callback URL şart mı
Garanti'nin kendi FAQ dokümanına göre evet
HTTPS ve dışarıdan erişilebilir olmalı
Önce sadece OAuth test edebilir miyim
Evet bank_test_connection bunun için var
App'e başka Garanti API'leri ekleyebilir miyim
Bu proje için ekleme
Sadece Account Information ve Account Transactions seçmek en güvenlisi
Response neden normalize edilmiyor
Garanti'nin gerçek response şemasını görmeden alan adı uydurmak istemiyoruz
İlk canlı veya sandbox response ile normalizer eklenebilir
Projeye katkı verebilir miyim
Tabii
Repo açık kaynak
Kaynaklar
Garanti API Developer Portal: https://developers.garantibbva.com.tr/
Garanti API Store FAQ: https://developers.garantibbva.com.tr/pages/SSS.html
Lisans
MIT
Available Tools
5 toolsbank_get_balancesCRead-onlyIdempotent
Read account information from Garanti. This uses the same Account Information product because the public portal does not document a separate balance API.
Inputs: page, pageSize.
bank_list_accountsDRead-onlyIdempotent
Call Garanti Account Information and return its read-only response.
Inputs: page, pageSize.
bank_list_transactionsBRead-onlyIdempotent
Call Garanti Account Transactions for an account and date range. No payment or transfer endpoint is available to this MCP.
Inputs: to (required), from (required), accountRef (required), page, +4 more.
bank_provider_statusARead-onlyIdempotent
Show Garanti API Store configuration status without exposing credentials.
Inputs: no named parameters.
bank_test_connectionARead-onlyIdempotent
Test Garanti OAuth client_credentials authentication. The access token is never returned.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
bank_list_accounts and bank_get_balances overlap significantly since both read account information, with bank_get_balances explicitly noting it uses the same Account Information product. bank_provider_status and bank_test_connection are both connectivity-related but distinguishable as status vs. authentication test. Other tools are distinct.
All tools share the bank_ prefix and most follow a verb_noun pattern (test_connection, list_accounts, get_balances, list_transactions). However, bank_provider_status uses a noun_noun construction, which is a minor deviation from the otherwise consistent pattern.
Five tools is well-scoped for a read-only banking data server. Each tool serves a clear functional area (status, auth test, accounts, balances, transactions), and no tool feels superfluous.
The server covers the core read-only operations for banking data: accounts, balances, and transactions, plus connection testing. It lacks payment/transfer functionality, but the description explicitly states these are unavailable in the underlying API, so the surface is appropriate for the stated purpose with minor gaps.
Related MCP Connectors
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Demo banking MCP server: accounts, transactions and payments. OAuth 2.1 with DPoP.
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for Isbank (Is Bankasi) developer API (Turkey). Enables access to accounts, balances, transactions, exchange rates, transfers, and credit cards via OAuth 2.0 authentication.814 npmMIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that securely connects Swedish/Nordic bank accounts to AI assistants, keeping all financial data local and encrypted.27 npmMIT
- AlicenseAqualityCmaintenanceA read-only MCP server for the open-banking.io PSD2 API that lets AI agents query personal bank balances and transactions via natural language, with zero-knowledge encryption ensuring all sensitive data is decrypted in-process and never exposed to third parties.4MIT
- AlicenseAqualityBmaintenanceSelf-hosted MCP server that securely connects your bank accounts via Enable Banking, offering read-only access to balances and transactions for AI assistants.12218 npm327MIT