e-Fatura MCP Server

e-Fatura MCP Server

Türkiye Gelir İdaresi Başkanlığı (GİB) e-Arşiv Fatura sistemi ile entegrasyon sağlayan MCP sunucusu.

📝 Read the full story on Medium (Turkish)

English | Türkçe

English

Features

• 📋 List and search e-Invoices
• 🔍 Get invoice details and XML
• ✏️ Create and cancel invoices
• ✅ Validate Turkish tax numbers (VKN/TCKN)
• 🎭 Demo mode - Test without real credentials
• 🔒 Production ready - Auto-switching between demo and real API

Quick Start

1. Install

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

2. Demo Mode (No credentials needed)

The server works immediately with mock data:

python -m efatura_mcp.server

For test: ⚠️ DEMO MODE: Using mock data

3. Use with Claude Desktop

Create config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

4. Test in Claude Desktop

Ask Claude:

List invoices

You should see 5 demo invoices!

Switch to Real GİB API

When ready to use real data:

1. Edit .env file:

GIB_USERNAME=your_vkn_here
GIB_PASSWORD=your_password_here
GIB_ENVIRONMENT=test

2. Restart the server

The server automatically switches to real API when credentials are provided.

Available MCP Tools

The server provides 7 MCP tools that Claude can use:

1. `list_invoices`

List e-Fatura invoices from GIB system.

Parameters:

• start_date (optional): Start date (YYYY-MM-DD)
• end_date (optional): End date (YYYY-MM-DD)
• limit (optional): Max invoices to return (default: 10)

Example: "Show me invoices from last month"

2. `get_invoice_detail`

Get detailed information for a specific invoice.

Parameters:

• invoice_id (required): Invoice ID/UUID

Example: "Show details for invoice ABC2024000001"

3. `get_invoice_xml`

Get invoice HTML/XML content in UBL-TR format.

Parameters:

• invoice_id (required): Invoice ID/UUID

Example: "Get XML for invoice ABC2024000001"

4. `create_invoice`

Create new e-Fatura invoice in GIB system.

Parameters:

• invoice_number, issue_date, supplier_vkn, supplier_name
• customer_vkn, customer_name, items[], total_amount
• currency (optional, default: TRY)

Example: "Create invoice for 1000 TRY to customer XYZ"

5. `cancel_invoice`

Cancel an existing invoice.

Parameters:

• invoice_id (required): Invoice ID to cancel
• reason (required): Cancellation reason

Example: "Cancel invoice ABC2024000001 due to error"

6. `search_invoices`

Search invoices with filters.

Parameters:

• customer_name, supplier_name (optional)
• min_amount, max_amount (optional)
• status (optional): approved, pending, cancelled

Example: "Find invoices over 10000 TRY", "Show pending invoices"

7. `validate_tax_number`

Validate Turkish tax number (VKN/TCKN).

Parameters:

• tax_number (required): 10 or 11 digit tax number

Example: "Validate tax number 1234567890"

Getting GİB Credentials

Get Credentials: Use your company's existing e-Fatura credentials

• Portal: https://earsivportal.efatura.gov.tr (production)
• Test Portal: https://earsivportaltest.efatura.gov.tr (test)

Project Structure

efatura-mcp-server/
├── src/
│   └── efatura_mcp/
│       ├── server.py           # Main MCP server
│       ├── gib_earsiv_client.py # Real GİB API client
│       └── mock_data.py        # Demo data
├── .env                        # Credentials (gitignored)
├── .env.example               # Template
└── README.md

See SECURITY.md for complete guidelines.

Requirements

• Python 3.10+
• Claude Desktop (or any MCP client)

Dependencies are auto-installed with pip install -e .

License

MIT

Türkçe

Özellikler

• 📋 e-Faturaları listele ve ara
• 🔍 Fatura detayları ve XML al
• ✏️ Fatura oluştur ve iptal et
• ✅ Vergi numarası doğrula (VKN/TCKN)
• 🎭 Demo modu - Gerçek credentials olmadan test et
• 🔒 Production hazır - Demo ve gerçek API arası otomatik geçiş

Hızlı Başlangıç

1. Kurulum

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

2. Demo Modu (Credential gerekmez)

Sunucu hemen mock data ile çalışır:

python -m efatura_mcp.server

Test için: ⚠️ DEMO MODE: Using mock data

3. Claude Desktop ile Kullan

Config dosyası oluştur:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: `~/Library/Application Support/Claude/claude