GIB API MCP Server

GIB (Gelir İdaresi Başkanlığı) gecikme zammı ve gecikme faizi hesaplama MCP server'ı. gib-gecikme-zammi-faizi Cloudflare Worker proxy üzerinden GİB Dijital Vergi Dairesi hesaplama servisine bağlanır.

Features

• Gecikme Zammı — Kesinleşmiş vergi borcu için aylık+günlük karma hesaplama (AATUHK m.51)
• Gecikme Faizi — İkmalen/resen tarhiyatlarda tam ay esasına göre hesaplama (VUK m.112)
• Kendi Worker'ın — Kendi Cloudflare Worker'ını deploy et, URL'i env var olarak ver

Prerequisites

Bu MCP server'ı kullanmak için kendi GİB API proxy worker'ınızı deploy etmeniz gerekir:

1. gib-gecikme-zammi-faizi reposunu fork edin
2. Cloudflare Workers'a deploy edin
3. Worker URL'inizi GIB_API_URL olarak ayarlayın

Quick Start

Claude Code

claude mcp add gib-api \
  -e GIB_API_URL="https://your-worker.your-account.workers.dev" \
  -e GIB_API_KEY="your-api-key" \
  -- npx -y gib-api-mcp

Claude Desktop

Add to your config file:

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

{
  "mcpServers": {
    "gib-api": {
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gib-api": {
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config:

{
  "mcpServers": {
    "gib-api": {
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

VS Code

Add to your VS Code settings (JSON):

"mcp": {
  "servers": {
    "gib-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "gib-api": {
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

GitHub Copilot

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "gib-api": {
      "command": "npx",
      "args": ["-y", "gib-api-mcp"],
      "env": {
        "GIB_API_URL": "https://your-worker.your-account.workers.dev"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.gib-api]
command = "npx"
args = ["-y", "gib-api-mcp"]

[mcp_servers.gib-api.env]
GIB_API_URL = "https://your-worker.your-account.workers.dev"

Install from Source

cd gib-api-mcp
npm install

Configuration

| Environment Variable | Required | Description | |---------------------|----------|-------------| | GIB_API_URL | Yes | Kendi Cloudflare Worker proxy URL'iniz. Deploy: gib-gecikme-zammi-faizi | | GIB_API_KEY | No | Worker'da API key koruması aktifse, X-API-Key header'ı olarak gönderilir |

Tools

Kesinleşmiş vergi borcu vadesinde ödenmezse uygulanan gecikme zammını hesaplar. Vade tarihinden ödeme tarihine kadar aylık + günlük karma sistem ile hesaplanır.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | odenecekMiktar | string | Yes | Borç tutarı (TL). Örnek: "10000.00" | | vadeTarihi | string | Yes | Vade tarihi (YYYYMMDD). Örnek: "20260101" | | odemeTarihi | string | Yes | Ödeme tarihi (YYYYMMDD). Örnek: "20260301" |

İkmalen, resen veya idarece yapılan tarhiyatlarda uygulanan gecikme faizini hesaplar. Sadece tam ay esasına göre hesaplanır, ay kesirleri dikkate alınmaz.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | odenecekMiktar | string | Yes | Borç tutarı (TL). Örnek: "10000.00" | | vadeTarihi | string | Yes | Normal vade tarihi (YYYYMMDD). Örnek: "20260101" | | odemeTarihi | string | Yes | Tahakkuk tarihi (YYYYMMDD). Örnek: "20260601" |

Usage Examples

# Gecikme zammı
1000 TL borcum var, vadesi 1 Ocak 2026, bugün ödesem ne kadar gecikme zammı öderim?

# Gecikme faizi
5000 TL'lik ikmalen tarhiyat, normal vade 1 Mart 2026, tahakkuk tarihi 1 Eylül 2026

License

MIT