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., "@gib-fatura-mcp Create a sales invoice for 5 units of service at 200 TL each with 18% KDV"
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.
GİB e-Arşiv portal üzerinde e-Fatura, e-Müstahsil Makbuzu ve e-SMM (Serbest Meslek Makbuzu) oluşturma, listeleme, imzalama vb. işlemler için MCP (Model Context Protocol) sunucusu.
mlevent/fatura PHP paketinin TypeScript/MCP portudur. Hesaplama mantığı (iskonto, KDV, tevkifat, özel matrah, stopaj, toplamlar) ve GİB istek formatları birebir taşınmıştır; hesaplamalar PHP paketinin kendi test senaryolarıyla doğrulanmıştır.
☢️ Bu araç vergiye tabi mali veri oluşturabilir. Belge imzalama (SMS doğrulama) işlemi faturanın resmen kesilmesi anlamına gelir; imzalanan belge değiştirilemez ve silinemez. Riskleri kullanan üstlenir.
Node.js 20.12+ gerekir. Sunucu stdio üzerinde çalışır:
git clone https://github.com/bevren/gib-fatura-mcp.git
cd gib-fatura-mcp
npm install
npm startclaude mcp add fatura -- npx tsx <bu-deponun-yolu>/src/index.tsclaude_desktop_config.json){
"mcpServers": {
"fatura": {
"command": "npx",
"args": ["tsx", "<bu-deponun-yolu>/src/index.ts"]
}
}
}Related MCP server: docnova-mcp
gib_login — gerçek kullanıcı: username + password; deneme için: testMode: true (otomatik test hesabı alınır, test portalında mali değer oluşmaz).
gib_create_invoice / gib_create_producer_receipt / gib_create_self_employed_receipt — belge taslağı oluşturur, tüm tutarlar otomatik hesaplanır, oluşan uuid (ETTN) döner.
gib_list_documents, gib_get_document, gib_get_document_html — kontrol/inceleme.
gib_start_sms_verification → gib_complete_sms_verification — belgeleri imzalar (☢️ resmi fatura keser; test hesaplarıyla çalışmaz).
gib_logout
Araç | Açıklama |
| Portala giriş (gerçek veya otomatik test hesabı) |
| Mevcut token ile oturum |
| Oturum kapatma / durum |
| e-Fatura taslağı (Satış, İade, Tevkifat, İstisna, Özel Matrah); |
| e-Müstahsil makbuzu taslağı |
| e-SMM taslağı |
| Düzenlenen belgeler (tarih aralığı + onay durumu/tür/alıcı/belge no/ETTN filtreleri, limit, sıralama) |
| Adıma düzenlenen belgeler |
| Belge detayı / en son belge |
| HTML çıktı |
| İndirme adresi / zip olarak diske kaydetme |
| Taslak silme |
| SMS ile belge imzalama |
| İptal/itiraz talepleri |
| GİB profil bilgileri okuma/güncelleme |
| VKN/TCKN ile mükellef sorgulama |
| Birimler, vergiler, tevkifat kodları, özel matrah nedenleri, fatura tipleri, para birimleri |
gib_create_invoice argümanları:
{
"vknTckn": "11111111111",
"aliciAdi": "Mert",
"aliciSoyadi": "Levent",
"mahalleSemtIlce": "Nilüfer",
"sehir": "Bursa",
"ulke": "Türkiye",
"malHizmetListe": [
{ "malHizmet": "Çimento", "miktar": 3, "birim": "M3", "birimFiyat": 1259, "kdvOrani": 18, "iskontoOrani": 25 }
]
}Dövizli fatura için paraBirimi + dovizKuru; iade için faturaTipi: "Iade" + iadeListe; tevkifat için faturaTipi: "Tevkifat" + kalemde tevkifatKodu; istisna için faturaTipi: "Istisna" + kalemde gtip; özel matrah için faturaTipi: "OzelMatrah" + kalemde ozelMatrahNedeni/ozelMatrahTutari. Kalemlere vergiler ile ek vergi eklenebilir (ör. {"vergi": "Damga", "oran": 15}).
npm run test:model # Hesaplama testleri (PHP paketinin ModelTest senaryoları)
npm run smoke # MCP el sıkışması + araç listesi (ağ gerektirmez)
npm run test:e2e # GİB TEST portalına karşı uçtan uca (test hesabı)Taslak silme: GİB portalı (en azından test ortamında) EARSIV_PORTAL_FATURA_SIL isteğini zaman zaman "Silinirken bir sorun oluştu." yanıtıyla reddediyor. İstek formatı PHP paketi ve fatura.js ile birebir aynıdır; sorun portal tarafındadır.
İndirme adresi: gib_get_download_url yalnızca tokenın alındığı IP adresinden çalışır; başka makineden erişim için gib_save_document_to_disk kullanın.
Adıma düzenlenen belgeler: GİB tarafında bu servis her zaman stabil çalışmıyor.
SMS imzalama test hesaplarıyla gerçekleştirilemez; mükellef sorgulama test ortamında boş döner.
Token süresi dolduğunda gib_login ile yeni token alınmalıdır.
İmzalanmış bir belge için iptal talebi oluşturur.
Inputs: uuid (required), explanation (required), belgeTuru.
☢️ DİKKAT: Belge imzalama, faturanın/makbuzun resmen kesilmesi işlemidir ve vergi sisteminde mali veri oluşturur. İmzalanan belge değiştirilemez ve silinemez. SMS ile gelen kod, gib_start_sms_verification'dan alınan oid ve imzalanacak belgelerin UUID listesi gönderilmelidir.
Inputs: oid (required), code (required), uuids (required), belgeTuru.
GİB e-Arşiv portalda e-Fatura taslağı oluşturur (Satış, İade, Tevkifat, İstisna, Özel Matrah). Tutar, iskonto, KDV ve vergi toplamları otomatik hesaplanır. uuid + belgeNumarasi birlikte verilirse portaldaki mevcut belge güncellenir. Belge taslak olarak kaydedilir; imzalanana kadar mali değeri yoktur.
Inputs: vknTckn (required), malHizmetListe (required), fax, not, +34 more.
GİB e-Arşiv portalda e-Müstahsil makbuzu taslağı oluşturur. GV stopajı ve toplamlar otomatik hesaplanır.
Inputs: vknTckn (required), aliciAdi (required), aliciSoyadi (required), malHizmetListe (required), +8 more.
GİB e-Arşiv portalda Serbest Meslek Makbuzu (e-SMM) taslağı oluşturur. Stopaj, KDV, tevkifat ve net tutarlar otomatik hesaplanır.
Inputs: vknTckn (required), malHizmetListe (required), saat, ulke, +19 more.
İmzalanmamış taslak belgeleri siler. Silinecek belgelerin UUID (ETTN) listesi verilmelidir.
Inputs: uuids (required), reason, belgeTuru.
Portalda kayıtlı bir belgenin detaylarını UUID (ETTN) ile getirir.
Inputs: uuid (required), belgeTuru.
Portalda kayıtlı belgenin HTML çıktısını getirir.
Inputs: uuid (required), signed.
Belgenin zip indirme adresini üretir. Not: Bu adrese yalnızca tokenın oluşturulduğu IP adresinden erişilebilir; farklı IP için gib_save_document_to_disk kullanın.
Inputs: uuid (required), signed, belgeTuru.
Portalda en son oluşturulan belgenin detaylarını getirir (varsayılan olarak son 1 yıl içinde arar).
Inputs: belgeTuru, recipientId.
TC Kimlik No veya Vergi Kimlik No ile mükellef bilgilerini (ünvan, ad, soyad, vergi dairesi) sorgular. Fatura kesmeden önce VKN doğrulamak için kullanılabilir. Test ortamında sonuç boş döner.
Inputs: vknTckn (required).
Belge oluştururken kullanılan sabit listeleri döndürür: birimler, vergiler, KDV tevkifat kodları, özel matrah nedenleri, fatura tipleri, para birimleri, itiraz yöntemleri.
Inputs: kind (required).
Belirtilen tarih aralığındaki iptal/itiraz taleplerini listeler.
Inputs: endDate (required), startDate (required).
Portalda kayıtlı kullanıcı (mükellef) profil bilgilerini getirir.
Inputs: no named parameters.
Belirtilen tarih aralığında düzenlenen belgeleri (taslak + imzalı) listeler. Onay durumu, belge türü, alıcı adı/VKN, belge no ve ETTN filtreleri uygulanabilir.
Inputs: endDate (required), startDate (required), ettn, limit, +9 more.
Belirtilen tarih aralığında adınıza düzenlenen belgeleri listeler. (Not: GİB tarafında bu servis zaman zaman stabil çalışmayabiliyor.)
Inputs: endDate (required), startDate (required), ettn, limit, +9 more.
GİB e-Arşiv portala giriş yapar ve oturum tokenı alır. testMode=true ve kullanıcı adı verilmezse otomatik olarak yeni bir test hesabı alınır. Gerçek kullanıcı bilgilerini muhasebecinizden veya GİB İnteraktif Vergi Dairesi'nden edinebilirsiniz.
Inputs: password, testMode, username.
GİB e-Arşiv portal oturumunu sonlandırır.
Inputs: no named parameters.
İmzalanmış bir belge için itiraz talebi oluşturur.
Inputs: uuid (required), documentId (required), explanation (required), documentDate (required), +2 more.
Portalda kayıtlı belgeyi zip olarak indirir ve diske kaydeder; kaydedilen dosyanın tam yolunu döndürür.
Inputs: uuid (required), signed, dirName, fileName, +1 more.
Mevcut oturum durumunu (token, kullanıcı, test modu) gösterir.
Inputs: no named parameters.
Daha önce alınmış bir oturum tokenını tanımlar; token süresi dolana kadar login olmadan işlem yapılabilir.
Inputs: token (required), testMode.
Belge imzalamak için SMS doğrulaması başlatır: portalda kayıtlı GSM numarasına doğrulama kodu gönderilir ve imzalama adımında kullanılacak Operasyon ID (oid) döndürülür. SMS doğrulama test hesaplarıyla çalışmaz.
Inputs: no named parameters.
Portalda kayıtlı kullanıcı profil bilgilerini günceller. Önce mevcut bilgiler okunur, verilen alanlar üzerine yazılır ve kaydedilir.
Inputs: fields (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
Each tool has a clearly distinct purpose covering different aspects of the document lifecycle: authentication, document creation (invoice, producer receipt, self-employed receipt), retrieval, deletion, signing, and dispute management. The use of unique verbs and nouns prevents any ambiguity.
All tools consistently use the 'gib_' prefix followed by a verb_noun pattern (e.g., gib_create_invoice, gib_list_documents, gib_get_document). This uniform naming convention makes the API predictable and easy to navigate.
With 24 tools, the count is on the higher side but justified by the complexity of the Turkish tax document domain which requires authentication, document creation (multiple types), signing, dispute management, and reference data operations. Each tool serves a distinct and necessary function.
The tool set covers the full lifecycle: authentication, session management, document creation (invoice, producer receipt, self-employed receipt), retrieval, listing, deletion, signing via SMS verification, cancellation, objection, reference data, user profile management, and recipient verification. No obvious gaps are present for the stated purpose of interacting with the GİB e-Arşiv portal.
MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creation.
Brazilian fiscal MCP server - issue NF-e, NFC-e, NFS-e, CT-e, MDF-e and DC-e via SEFAZ.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
