e-Fatura MCP nedir? GİB e-Arşiv faturalarını asistana bağlamak, kurulum ve riskler

Asistanına faturalarını sorarsın ya da yeni fatura kestirirsin; e-Fatura MCP GİB e-Arşiv portalına senin adına giriş yapıp faturaları listeler, ayrıntı ve HTML/XML getirir, fatura oluşturur ve iptal eder. 7 aracın ikisi yazar: fatura oluşturma taslağı hemen imzalar ve araçta onay adımı yok. Kimlik vermezsen sahte veriyle demo modunda çalışır, ama bunun uyarısı sohbette görünmez. Gerçek modda portal şifren `.env` dosyasında düz metin durur; kod GİB'in resmî bir API'sini değil, portalın web arayüzünün iç uç noktalarını çağırır. Tek bir geliştiricinin açık kaynak (MIT) topluluk projesi; depo 3 commit, son güncelleme Aralık 2025. Bu sayfa mali müşavirlik ya da hukuki görüş değildir.

Ne yapar: Asistana GİB e-Arşiv portalında fatura listeletir ve kestirir
Tür: MCP sunucusu (topluluk projesi, yerel)
Nerede: README'de yalnız Claude Desktop adımı var
Yazar mı?: Evet: fatura oluşturur ve iptal eder
Resmî mi?: Hayır; portalın iç uç noktaları
Bakım: Son güncelleme 05.12.2025
Ücret: Ücretsiz (MIT); GİB hesabı senin

e-Fatura MCP ne işe yarar?

MCP, yapay zekâ programlarının dış araçlara bağlanma standardıdır. Bu sunucu asistanına GİB e-Arşiv portalındaki faturalarını gösterir: "geçen ayki faturaları listele" ya da "şu faturanın ayrıntısını getir" diyebilirsin; asistan sunucudaki aracı çağırır, sunucu da portala senin kullanıcı adınla girip veriyi alır. İstersen yeni fatura oluşturup iptal de ettirebilir (aşağıdaki uyarıya bak).

SenFaturayı sorarsın ya da kestirirsin

AsistanClaude Desktop

e-Fatura MCPBilgisayarında çalışır

GİB e-Arşiv portalıPortalın iç uç noktaları, senin şifrenle

Fatura oluşturma taslağı hemen imzalar; araçta onay adımı yok.

e-Arşiv faturalarını listelemekNe alırsın: Metin liste ve ayrıntı; asistan yanıtıAyrı kurulum gerekir

Kime yarar: README, "şirketinin mevcut e-Fatura kimlik bilgilerini kullan" diyor. Küçük işletme sahibi için bir deneme aracıdır; üretim muhasebesi için tasarlanmış bir ürün gibi sunulmuyor (pyproject sınıflandırması "Alpha").

Bu araç resmî bir GİB ya da özel entegratör ürünü değil. Kod, portalın web arayüzünün kendi iç uç noktalarını (giriş, taslak oluşturma, imzalama, silme) çağırıyor; kod başlığı bunu bir başka açık kaynak projeden (f/fatura) uyarladığını söylüyor. GİB bu uç noktaları değiştirirse sunucu bozulabilir. Bu sayfa mali müşavirlik ya da hukuki görüş değildir.

e-Fatura MCP nasıl kurulur, GİB şifresi nereye girilir?

Kurulum README'den aynen: Python 3.10+ gerekir, paket PyPI'de yok, depo klonlanır. Komutlar:

Terminal

› git clone https://github.com/reyhansunduk/efatura-mcp-server.git
cd efatura-mcp-server
pip install -e .

README'deki yapılandırma dosyası konumları: Windows'ta %APPDATA%\Claude\claude_desktop_config.json, macOS'ta ~/Library/Application Support/Claude/claude_desktop_config.json. İçine şunu ekle (cwd değerini klonladığın klasörle değiştir), sonra Claude Desktop'ı yeniden aç:

claude_desktop_config.json

› {
  "mcpServers": {
    "efatura": {
      "command": "python",
      "args": ["-m", "efatura_mcp.server"],
      "cwd": "C:\path\to\efatura-mcp-server"
    }
  }
}

Kimlik bilgisi nereye girilir: Gerçek GİB verisi için proje klasöründeki .env dosyasına (örnek: .env.example) üç satır yazılır. Sunucu kimlik bilgilerini bu dosyadan okur; cwd ayarı bu yüzden önemli.

.env

› GIB_USERNAME=vkn_buraya
GIB_PASSWORD=sifre_buraya
GIB_ENVIRONMENT=test

Nerede saklanır: düz metin bir dosyada, bilgisayarında. Şifre şifrelenmez. SECURITY.md dosyayı .gitignore'da tutmayı, dosya izinlerini yalnız sana açmayı (Linux/macOS chmod 600, Windows icacls) ve şifreyi düzenli değiştirmeyi öneriyor. Sunucu başlarken kullanıcı adını (VKN) günlüğe de yazıyor. Şifreni asla sohbete yazma.

GIB_ENVIRONMENT varsayılan olarak test: test portalı (earsivportaltest.efatura.gov.tr). Gerçek faturalar için production yazılır (earsivportal.efatura.gov.tr). Bilinmeyen bir değer yazarsan sunucu sessizce test adresine düşer. README ve .env.example, kimlik bilgisini şirketin mevcut e-Arşiv kimliğinden almanı, yoksa GİB'den ya da bir entegratörden istemeni söylüyor (entegratör için .env.example "ücretli hizmet" diyor, tutar vermiyor).

İlk denemede .env dosyasını boş bırak ya da hiç oluşturma: sunucu demo moduna geçer ve sahte faturalar gösterir. Önce araçların nasıl çalıştığını gör, sonra test ortamının kimliğiyle dene.

e-Fatura MCP nasıl kullanılır, demo modu nedir?

Kurduktan sonra asistana normal cümleyle yaz. README'nin ilk testi "Faturaları listele": demo modunda 5 örnek fatura görmen gerekir.

Demo testi"e-Fatura MCP ile faturaları listele."

Fatura ayrıntısı"Geçen ayki faturaları listele, sonra ilk faturanın ayrıntılarını getir. Hiçbir şeyi oluşturma ya da iptal etme."

Yalnız okuma"Bu oturumda yalnız okuma araçlarını kullan: fatura listeleme, ayrıntı ve XML. Fatura oluşturma ve iptal araçlarını çağırma."

Demo modu nasıl anlaşılır: README sunucu başlarken "DEMO MODE: Using mock data" uyarısı yazdığını söylüyor, ama bu uyarı sunucu günlüğüne gidiyor. Araç yanıtlarında (koda göre) demo etiketi yok: demo modunda bile "Invoice Created Successfully" gibi başarı mesajı gelebilir. Gerçek mi sahte mi olduğunu asistanın cevabından değil, .env dosyandan ve GİB portalından kontrol et.

Yazma araçlarını çağırtmadan önce portaldan doğrula. Araçta onay adımı yok: asistan create_invoice ya da cancel_invoice çağırırsa işlem gerçek ortamda hemen yapılır. İstemcinde araç bazında izin sorusu açıksa her çağrıda "izin ver" demeden önce parametreleri oku.

e-Fatura MCP hangi programlarda çalışır?

Sunucu yerelde çalışan bir Python süreci olarak stdio üzerinden konuşur. Bilgisayarında çalıştığı için uzak bir sunucuya ihtiyaç duymaz; yalnız GİB portalına çıkar.

Claude DesktopVar	README'de adım adım yapılandırma var.
Başka MCP istemcileriNet değil	README "Claude Desktop (veya herhangi bir MCP client)" diyor ama başka istemci için adım vermiyor. Sunucu standart MCP; "belgede yok" demek "çalışmaz" demek değildir.
Claude Code, Cursor, VS Code, ChatGPTNet değil	README'de adları geçmiyor.

e-Fatura MCP neye erişir, hangi işlemler geri alınamaz?

README ve koddaki 7 araç. Okuyan araçlarla yazan araçlar ayrı gösterilir; yazan araçlar gerçek portalda işlem yapar.

Araç	Ne yapar	Okur / yazar
`list_invoices`	Tarih aralığında faturaları listeler (varsayılan başlangıç 2024-01-01, varsayılan 10 kayıt)	Okur
`get_invoice_detail`	Bir faturanın ayrıntısını getirir	Okur
`get_invoice_xml`	Faturanın HTML/XML (UBL-TR) içeriğini getirir	Okur
`search_invoices`	Müşteri, tutar, durum süzgeciyle arar; portalda aramaz, ilk 100 kaydı süzer	Okur
`validate_tax_number`	Yalnız 10 ya da 11 haneli rakam biçimine bakar; GİB'e sormaz	Denetler
`create_invoice`	Taslak fatura oluşturur ve hemen imzalar	YAZAR, geri dönüşsüz
`cancel_invoice`	Faturayı iptal etmeyi dener (kod taslak silme komutunu çağırır)	YAZAR, geri dönüşsüz

Fatura kesme

create_invoice taslağı oluşturur ve imzalar; imza başarısız olsa bile kod faturanın numarasını döndürür. Fatura gövdesi "basitleştirilmiş eşleme": kodda KDV ve vergi alanları sabit sıfır, adres alanları boş. Bu yüzden asistanın oluşturduğu bir fatura muhasebe açısından eksik ya da hatalı olabilir; sorumluluk sende.

İptal

cancel_invoice portalın taslak silme komutunu çağırır (kod "taslak faturayı iptal et" der). Araç açıklaması ise "mevcut faturayı iptal eder" diyor. İmzalı bir faturada ne yaptığı belgede yazmıyor. Hatalı faturayı geri almak ya da düzeltmek için portalın kendi akışını ve mali müşavirini esas al.

Kimlik bilgisi

Portal şifren .env dosyasında düz metin durur ve her oturumda portala gönderilir. Bilgisayarındaki başka bir program bu dosyayı okuyabilir. Önce test ortamını kullan, gerçek şifreni paylaşılan ya da buluta senkron bir klasörde tutma.

Veri

Sunucu bilgisayarında çalışır ve yalnız GİB portalına çıkar; kodda başka bir adrese gönderim ya da telemetri görünmüyor. Ama faturalardaki müşteri adı, VKN/TCKN ve tutarlar asistana yanıt olarak döner; yani kullandığın yapay zekâ servisinin veri koşullarına tabidir.

Güvenlik taraması (14.10.2026): GitHub Security Advisories boş, genel GitHub advisory aramasında kayıt yok, OSV'de kayıt yok (paket PyPI'de de yok). Kayıtlı uyarı görünmüyor; bu "güvenli" demek değildir. Tek geliştirici, 3 commit, en son güncelleme 05.12.2025, sürüm etiketi yok.

e-Fatura MCP ücretsiz mi?

Yazılım ücretsiz ve MIT lisanslı. README ve pyproject'te ücret ya da plan geçmiyor. Gerçek kullanım için GİB e-Arşiv portalında hesabın olması gerekir; o hesabın koşulları ve varsa entegratör ücretleri ayrı konudur. Asistanın kendi aboneliği de ayrıdır.

Yapabilirsin

MIT: kodu kullanmak, değiştirmek, dağıtmak serbest

Yasak

Garanti yok: SECURITY.md "olduğu gibi sunulur, sorumluluk kullanıcıdadır" diyor
Kullanıcı GİB hizmet koşullarına ve vergi/veri koruma mevzuatına uymaktan kendisi sorumlu (SECURITY.md)

Kaynak: README, LICENSE, SECURITY.md. Faturalama, e-Arşiv kullanım yükümlülükleri ve yetki konularında mali müşavirine danış; bu sayfa mali müşavirlik ya da hukuki görüş değildir.

Sık sorunlar ve çözümleri

Ne oluyor	Ne yapmalı
Fatura listesi boş geliyor	Kod, liste isteği hata verirse hatayı günlüğe yazıp boş liste döndürüyor; "fatura yok" ile "bağlanamadı" ayırt edilemez. Sunucu günlüğüne ve kimlik/ortam ayarına bak.
Faturalar geliyor ama sahte görünüyor	Kimlik tanımlı değilse ya da yer tutucu değerdeyse sunucu demo moduna düşer; uyarı yalnız günlükte. `.env` dosyasını ve `cwd` ayarını kontrol et.
Sunucu `.env` dosyasını bulamıyor	Yapılandırmadaki `cwd` klonladığın klasör olmalı; dosya orada aranır.
Arama eski faturaları bulmuyor	`search_invoices` portalda aramaz, `list_invoices(limit=100)` sonucunu süzer; 100 kayıttan fazlası görünmez.
Vergi numarası "geçerli" çıktı ama mükellef değil	`validate_tax_number` yalnız rakam sayısına bakar; GİB'den mükellef sorgusu yapmaz.

e-Fatura MCP nasıl kaldırılır?

Bağlantı: claude_desktop_config.json içindeki efatura girdisini sil ve uygulamayı yeniden aç.
Şifre: Proje klasöründeki .env dosyasını sil ve GİB portalında şifreni değiştir.
Kod: Klonladığın klasörü ve pip install -e . ile kurulan paketi kaldırabilirsin.

README kaldırma adımı vermiyor; yukarıdakiler dosyaların nerede durduğundan çıkarıldı. SECURITY.md, kimlik bilgisi sızdıysa şifreyi hemen değiştirmeyi ve portal erişim kayıtlarını incelemeyi söylüyor.

Sık sorulan sorular

e-Fatura MCP nedir?

Tek bir geliştiricinin açık kaynak topluluk projesi: GİB e-Arşiv portalındaki faturaları yapay zekâ asistanına açan, fatura oluşturup iptal edebilen bir MCP sunucusu.

GİB şifremi vermem gerekir mi?

Gerçek veri için evet: kullanıcı adı (VKN) ve şifre proje klasöründeki .env dosyasına düz metin yazılır. Vermezsen sunucu sahte veriyle demo modunda çalışır. Şifreni sohbete yazma.

Yapay zekâ ile fatura kesilebilir mi, geri alınır mı?

create_invoice taslağı oluşturup hemen imzalar ve araçta onay adımı yok. İptal aracı portalın taslak silme komutunu çağırıyor; imzalı faturada ne yaptığı belgede yazmıyor. Hata durumunda portalın kendi akışını ve mali müşavirini esas al.

Demo modunda mıyım, nasıl anlarım?

Kimlik tanımlı değilse sunucu demo moduna düşer ve uyarıyı yalnız günlüğe yazar; araç yanıtlarında demo etiketi yok. .env dosyanı ve cwd ayarını kontrol et.

Bu GİB'in resmî aracı mı?

Hayır. Kod, e-Arşiv portalının web arayüzünün iç uç noktalarını çağırıyor ve bir başka topluluk projesinden uyarlanmış. GİB bu uç noktaları değiştirirse çalışmayabilir.

Güvenli mi, bakımı var mı?

GitHub ve OSV taramasında kayıtlı uyarı görünmüyor; bu güvenli demek değildir. Depo 3 commit, son güncelleme 05.12.2025, sürüm 0.1.0 (Alpha). Bu sayfa mali müşavirlik ya da hukuki görüş değildir.

İlgili rehberler

Borsa MCP efatura-kontrol İhale MCP iyzico MCP (qwertyvan)iyzico MCP (seyithanalkan)Paraşüt MCP

Kaynaklar

Resmî kaynaklarda net olmayanlar: İmzalı faturada cancel_invoice'ın ne yaptığı · kodun bugünkü GİB portalıyla çalışıp çalışmadığı · oluşturulan faturadaki KDV/vergi alanlarının doğruluğu (kodda sabit sıfır) · GİB'in portal şifresinin üçüncü taraf yazılımda kullanımına dair koşulları · Claude Desktop dışındaki istemcilerde çalıştığı. Her biri ilgili bölümde yazılı.