🧾 fatura-mcp

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.

Kurulum

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 start

Claude Code

claude mcp add fatura -- npx tsx <bu-deponun-yolu>/src/index.ts

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "fatura": {
      "command": "npx",
      "args": ["tsx", "<bu-deponun-yolu>/src/index.ts"]
    }
  }
}

Related MCP server: einvoice-mcp

Kullanım Akışı

1. 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).

2. 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.

3. gib_list_documents, gib_get_document, gib_get_document_html — kontrol/inceleme.

4. gib_start_sms_verification → gib_complete_sms_verification — belgeleri imzalar (☢️ resmi fatura keser; test hesaplarıyla çalışmaz).

5. gib_logout

Araçlar

Örnek: Satış Faturası

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}).

Testler

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ı)

Bilinen Notlar

• 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.