What is e-Fatura MCP? Connecting Turkish GİB e-archive invoices to an assistant: setup and risks

In Turkey, many businesses issue invoices electronically through the e-Arşiv (e-archive invoice) portal of GİB (Turkish Revenue Administration). With e-Fatura MCP you ask your assistant about your invoices or have it issue a new one; the server logs in to the GİB e-Arşiv portal on your behalf and lists invoices, fetches details and HTML/XML, creates invoices and cancels them. Two of its 7 tools write: invoice creation signs the draft immediately, and the tool has no confirmation step. If you give it no credentials it runs in demo mode with fake data, but that warning does not appear in the chat. In real mode your portal password sits in plain text in a `.env` file; the code does not call an official GİB API but the internal endpoints of the portal's web interface. It is an open-source (MIT) community project by a single developer; the repository has 3 commits, last updated December 2025. This page is not accounting or legal advice.

What it does: Has the assistant list and issue invoices on the GİB e-Arşiv portal
Type: MCP server (community project, local)
Where: The README only gives steps for Claude Desktop
Does it write?: Yes: it creates and cancels invoices
Official?: No; internal endpoints of the portal
Maintenance: Last updated 12/05/2025
Price: Free (MIT); you bring your own GİB account

What does e-Fatura MCP do?

MCP is the standard AI programs use to connect to outside tools. This server shows your assistant the invoices on your GİB e-Arşiv portal account: you can say "list last month's invoices" or "get the details of this invoice"; the assistant calls the tool on the server, and the server logs in to the portal with your username and fetches the data. If you want, it can also create and cancel invoices (see the warning below).

YouYou ask about an invoice or have one issued

AssistantClaude Desktop

e-Fatura MCPRuns on your computer

GİB e-Arşiv portalInternal endpoints of the portal, with your password

Invoice creation signs the draft immediately; the tool has no confirmation step.

List e-Arşiv invoicesWhat you get: Text list and details; assistant responseNeeds a separate setup

Who it is for: the README says "use your company's existing e-Fatura credentials". For a small business owner it is a tool to experiment with; it is not presented as a product built for production accounting (its pyproject classification is "Alpha").

This tool is not an official product of GİB or of a private e-invoice integrator. The code calls the portal web interface's own internal endpoints (login, draft creation, signing, deletion); the code header says it was adapted from another open-source project (f/fatura). If GİB changes these endpoints, the server may break. This page is not accounting or legal advice.

How do you install e-Fatura MCP, and where does the GİB password go?

Installation, exactly as in the README: Python 3.10+ is required, the package is not on PyPI, and you clone the repository. Commands:

Terminal

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

Config file locations from the README: on Windows %APPDATA%\Claude\claude_desktop_config.json, on macOS ~/Library/Application Support/Claude/claude_desktop_config.json. Add the following (replace the cwd value with the folder you cloned into), then reopen Claude Desktop:

claude_desktop_config.json

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

Where the credentials go: for real GİB data, three lines go into the .env file in the project folder (template: .env.example). The server reads the credentials from this file, which is why the cwd setting matters.

.env

› GIB_USERNAME=your_vkn_here
GIB_PASSWORD=your_password_here
GIB_ENVIRONMENT=test

Where it is stored: in a plain-text file on your computer. The password is not encrypted. SECURITY.md recommends keeping the file in .gitignore, restricting file permissions to yourself only (Linux/macOS chmod 600, Windows icacls) and changing the password regularly. When the server starts it also writes the username (VKN, the Turkish tax ID number) to the log. Never type your password into the chat.

GIB_ENVIRONMENT defaults to test: the test portal (earsivportaltest.efatura.gov.tr). For real invoices you write production (earsivportal.efatura.gov.tr). If you enter an unknown value, the server silently falls back to the test address. The README and .env.example tell you to use your company's existing e-Arşiv credentials, or otherwise to request them from GİB or from an integrator (for the integrator, .env.example says "paid service" and gives no amount).

On your first try, leave the .env file empty or do not create it at all: the server switches to demo mode and shows fake invoices. See how the tools work first, then try with test-environment credentials.

How do you use e-Fatura MCP, and what is demo mode?

Once installed, write to the assistant in ordinary sentences. The README's first test is "List invoices": in demo mode you should see 5 sample invoices.

Demo test"List the invoices with e-Fatura MCP."

Invoice details"List last month's invoices, then get the details of the first invoice. Do not create or cancel anything."

Read-only"In this session use only the read tools: invoice listing, details and XML. Do not call the invoice creation or cancellation tools."

How to tell you are in demo mode: the README says the server prints a "DEMO MODE: Using mock data" warning when it starts, but that warning goes to the server log. Tool responses carry no demo label (according to the code): even in demo mode you can get a success message such as "Invoice Created Successfully". Check whether data is real or fake in your .env file and on the GİB portal, not from the assistant's answer.

Verify on the portal before you let it call the write tools. The tool has no confirmation step: if the assistant calls create_invoice or cancel_invoice, the action happens immediately in the live environment. If your client asks for permission per tool, read the parameters before you click "allow" on each call.

Which apps does e-Fatura MCP work in?

The server runs locally as a Python process and talks over stdio. Because it runs on your computer, it needs no remote server; it only connects out to the GİB portal.

Claude DesktopYes	The README has step-by-step configuration.
Other MCP clientsUnclear	The README says "Claude Desktop (or any MCP client)" but gives no steps for other clients. The server is standard MCP; "not in the documentation" does not mean "does not work".
Claude Code, Cursor, VS Code, ChatGPTUnclear	Not named in the README.

What does e-Fatura MCP access, and which actions cannot be undone?

The 7 tools in the README and the code. Read tools and write tools are shown separately; write tools perform actions on the real portal.

Tool	What it does	Reads / writes
`list_invoices`	Lists invoices in a date range (default start 2024-01-01, default 10 records)	Reads
`get_invoice_detail`	Gets the details of an invoice	Reads
`get_invoice_xml`	Gets the invoice's HTML/XML (UBL-TR) content	Reads
`search_invoices`	Searches with customer, amount and status filters; does not search on the portal, filters the first 100 records	Reads
`validate_tax_number`	Only checks for a 10- or 11-digit number format; does not query GİB	Checks
`create_invoice`	Creates a draft invoice and signs it immediately	WRITES, irreversible
`cancel_invoice`	Tries to cancel an invoice (the code calls the draft deletion command)	WRITES, irreversible

Issuing invoices

create_invoice creates the draft and signs it; even if signing fails, the code returns the invoice number. The invoice body is a "simplified mapping": in the code, the VAT (KDV) and tax fields are fixed at zero and the address fields are empty. So an invoice created by the assistant may be incomplete or wrong from an accounting point of view; the responsibility is yours.

Cancellation

cancel_invoice calls the portal's draft deletion command (the code says "cancel draft invoice"). The tool description, however, says "cancels an existing invoice". What it does on a signed invoice is not documented. To undo or correct a wrong invoice, rely on the portal's own process and your accountant.

Credentials

Your portal password sits in plain text in the .env file and is sent to the portal in every session. Another program on your computer can read this file. Use the test environment first, and do not keep your real password in a shared or cloud-synced folder.

Data

The server runs on your computer and connects out only to the GİB portal; the code shows no sending to any other address and no telemetry. But the customer names, VKN/TCKN (Turkish tax ID / national ID numbers) and amounts on your invoices come back to the assistant as responses, so they are subject to the data terms of the AI service you use.

Security scan (October 14, 2026): GitHub Security Advisories is empty, the general GitHub advisory search has no entries, and OSV has no entries (the package is not on PyPI either). No recorded advisory appears; that does not mean "safe". Single developer, 3 commits, last updated December 5, 2025, no release tag.

Is e-Fatura MCP free?

The software is free and MIT-licensed. The README and pyproject mention no fee or plan. For real use you need an account on the GİB e-Arşiv portal; that account's terms and any integrator fees are a separate matter. Your assistant's own subscription is also separate.

Allowed

MIT: you are free to use, modify and distribute the code

Not allowed

No warranty: SECURITY.md says it is "provided as is, responsibility lies with the user"
The user is responsible for complying with GİB terms of service and with tax and data protection law (SECURITY.md)

Source: README, LICENSE, SECURITY.md. For invoicing, e-Arşiv usage obligations and authorization questions, consult your accountant; this page is not accounting or legal advice.

Common problems and fixes

What happens	What to do
The invoice list comes back empty	If the list request fails, the code writes the error to the log and returns an empty list; "no invoices" and "could not connect" cannot be told apart. Check the server log and your credentials/environment settings.
Invoices come back but look fake	If no credentials are set, or they are still placeholder values, the server falls back to demo mode; the warning is only in the log. Check the `.env` file and the `cwd` setting.
The server cannot find the `.env` file	The `cwd` in the configuration must be the folder you cloned into; the file is looked for there.
Search does not find older invoices	`search_invoices` does not search on the portal; it filters the result of `list_invoices(limit=100)`, so anything beyond 100 records is not visible.
A tax number came out "valid" but is not a registered taxpayer	`validate_tax_number` only counts digits; it does not run a taxpayer lookup with GİB.

How do you remove e-Fatura MCP?

Connection: Delete the efatura entry in claude_desktop_config.json and reopen the app.
Password: Delete the .env file in the project folder and change your password on the GİB portal.
Code: You can remove the cloned folder and the package installed with pip install -e ..

The README gives no removal steps; the steps above follow from where the files are stored. SECURITY.md says that if credentials leak, you should change the password immediately and review the portal access logs.

Frequently asked questions

What is e-Fatura MCP?

An open-source community project by a single developer: an MCP server that opens the invoices on the Turkish GİB e-Arşiv (e-archive invoice) portal to an AI assistant and can create and cancel invoices.

Do I have to give it my GİB password?

For real data, yes: the username (VKN, the Turkish tax ID number) and password are written in plain text to the .env file in the project folder. If you do not provide them, the server runs in demo mode with fake data. Do not type your password into the chat.

Can AI issue an invoice, and can it be undone?

create_invoice creates the draft and signs it immediately, and the tool has no confirmation step. The cancel tool calls the portal's draft deletion command; what it does on a signed invoice is not documented. If something goes wrong, rely on the portal's own process and your accountant.

How do I know if I am in demo mode?

If no credentials are set, the server falls back to demo mode and writes the warning only to the log; tool responses carry no demo label. Check your .env file and the cwd setting.

Is this an official GİB tool?

No. The code calls internal endpoints of the e-Arşiv portal's web interface and was adapted from another community project. If GİB changes these endpoints, it may stop working.

Is it safe, and is it maintained?

No recorded advisory appears in the GitHub and OSV scans; that does not mean it is safe. The repository has 3 commits, was last updated December 5, 2025, and is version 0.1.0 (Alpha). This page is not accounting or legal advice.

Sources

Not clear in the official sources: What cancel_invoice does on a signed invoice · whether the code works with today's GİB portal · whether the VAT/tax fields on created invoices are correct (fixed at zero in the code) · GİB's terms on using the portal password in third-party software · whether it works in clients other than Claude Desktop. Each is covered in the relevant section.