What is efatura-kontrol? Checking Turkish e-invoice XML before it goes to GİB: setup and limits

In Turkey, invoices are issued electronically through GİB (Turkish Revenue Administration) as e-Fatura (e-invoice), e-Arşiv (e-archive invoice) and e-İrsaliye (e-waybill) XML files. You give your assistant one of these XML files or an envelope XML; efatura-kontrol checks it on your own computer against the XSD and Schematron rules GİB publishes, before it is sent to GİB, and returns every finding with a line number, an explanation in Turkish and a suggested fix. It is meant for developers and e-invoice integrators: it does not issue invoices or send anything to GİB, it only reads the file. It is an open-source community project by a single developer (Berkant Acun) with no link to GİB; it is MIT-licensed and free, and according to the README no data leaves your machine. Important: the only version published on PyPI is 0.1.0 (September 21, 2026) and it offers 5 tools; the 6th tool in the README (sample invoice) has not been released yet.

What it does: Checks e-Fatura XML against GİB rules
Type: MCP server (community project; local)
Where: Claude Desktop, Claude Code, Cursor, Cline
Data: Runs locally; README: nothing goes over the network
Official?: No; not a GİB product, version 0.1.0, 2 stars
Turkish: Finding explanations and fixes are in Turkish
Price: Free (MIT); no account or key

What does efatura-kontrol do?

MCP is the standard AI programs use to connect to outside tools. With efatura-kontrol you can tell your assistant "check this invoice XML against GİB rules" or "what does this error code mean?"; the assistant calls the tool on the server and explains the result to you in Turkish. If you build software that produces Turkish e-invoice XML, it lets you find errors on your own computer before the file goes to GİB or to your integrator.

YouYou ask it to check an invoice XML

AssistantClaude Desktop, Claude Code, Cursor, Cline

efatura-kontrolRuns on your computer

GİB XSD and Schematron rulesLine number, explanation in Turkish, fix

It does not issue invoices or send anything to GİB; according to the README, no data goes over the network.

Check XML against GİB rulesWhat you get: List of findings: code, level, GİB message, line number, explanation in Turkish and fixNeeds a separate setup

According to the README, the check has four layers: XML well-formedness and size; the OASIS UBL 2.1 XSD schemas and GİB envelope schemas; the Schematron from GİB's e-Fatura Package (rule set and code lists); and line, tax, withholding and grand-total arithmetic plus the structure of the electronic signature. Every finding carries a level: error (GİB rejects it), warning (GİB may not reject it, but the recipient might), info (e.g. "the document is not signed yet").

Tool	Type	What it does
`belge_dogrula`	Read-only	Full check from a file path or XML text
`belge_ozeti`	Read-only	Scenario, parties, lines, taxes, grand totals, signature status
`bulgu_acikla`	Read-only	Explanation and fix for a finding code
`kod_listesi`, `kod_listeleri`	Read-only	GİB code lists (unit, currency, tax, exemption, etc.) and their values
`ornek_fatura`	Read-only (returns XML, writes no file)	Unsigned sample invoice. In the README, not in the published 0.1.0 release

Source: README (MCP server) and CHANGELOG. The README says all tools are read-only and none of them writes files. There is no tool with write access.

Who it is for: developers, integrators and accounting-software builders who produce Turkish e-invoice XML. If you are a business owner who just wants to issue invoices, this tool will not issue one for you; your integrator's own interface does that job.

How do you install efatura-kontrol?

The server runs from the efatura-kontrol package on PyPI. Prerequisite: Python 3.10 or later. Dependencies are lxml and SaxonC-HE (~40 MB). If you use uvx, you also need the uv program. The command and JSON below are copied as-is from the README.

The README gives the same configuration for Claude Desktop, Claude Code and Cursor. Add this to your client's MCP settings file (the README does not give the path of the settings file):

MCP config› {"mcpServers": {"efatura-kontrol": {"command": "uvx", "args": ["efatura-kontrol", "mcp"]}}}

For Claude Code the README shows the same JSON; it does not give a separate claude mcp add command. Add the JSON to Claude Code's MCP settings file:

MCP config› {"mcpServers": {"efatura-kontrol": {"command": "uvx", "args": ["efatura-kontrol", "mcp"]}}}

The README shows the same JSON for Cursor too:

MCP config› {"mcpServers": {"efatura-kontrol": {"command": "uvx", "args": ["efatura-kontrol", "mcp"]}}}

The README says agents like Cline can do the installation on their own using the llms-install.md file. That file describes adding the same uvx entry (plus a disabled field and an optional autoApprove field) to the mcpServers object in cline_mcp_settings.json.

Install› pip install efatura-kontrol

If uv cannot be installed, llms-install.md gives this fallback: after the pip install, set command to efatura-kontrol and args to ["mcp"] in the configuration.

SaxonC-HE (~40 MB) downloads on the first run. So that your client does not time out, llms-install.md recommends running uvx efatura-kontrol --version once beforehand. If the client cannot find uvx on Windows, the same file says to put the full path of uvx.exe in the command field.

The only published version is 0.1.0 (September 21, 2026). The README and llms-install.md, however, also describe later additions: the ornek_fatura tool, the mcp --http remote mode and a Docker image. According to the CHANGELOG these are under [Unreleased]; so the version you get with uvx efatura-kontrol mcp has 5 tools and may not include these three. Check which version you are running with uvx efatura-kontrol --version.

Remote mode (mcp --http, Docker image) is described in the README and protected with X-API-Key; since it is not in the published version, it is not given as an installation step on this page.

How do you use efatura-kontrol?

After installing, mention efatura-kontrol in the chat and give it the file path (or the XML text). The tool returns the findings; the interpretation comes from the assistant and can be wrong, so before applying a fix, also read the finding code and GİB's original message.

Check an invoice"Use efatura-kontrol to check the file C:\invoices\invoice.xml. List errors, warnings and info items separately; for each one, give the line number, GİB's original message and the fix. Do not modify the file."

Ask about an error code"Use efatura-kontrol to explain the finding sch-GeneralUnitCodeCheck-1 and pull the valid unit codes from the code list."

Even if the tool says "valid", that does not mean GİB will accept the invoice. Per the README, "valid" only means the file passes the XSD and Schematron that GİB publishes; it does not run the live checks of GİB's system (is the taxpayer registered, is the recipient alias valid, is the invoice number a duplicate) and it does not verify the signature cryptographically. This is not accounting, tax or legal advice.

Which programs does efatura-kontrol work in?

Claude DesktopYes	Named in the README's MCP section; local stdio server.
Claude CodeYes	Named in the README's MCP section; it gives a JSON config rather than a separate command.
CursorYes	Named in the README's MCP section.
ClineYes	llms-install.md gives a separate installation guide for this client.
ChatGPT, Claude in the browser, other programsUnclear	Not named in the documentation. The server runs as a local program; "not in the docs" does not mean "does not work".

What does efatura-kontrol access, and where does the data go?

What it reads

It reads the e-Fatura, e-Arşiv, e-İrsaliye or envelope XML files you give it (by file path or as XML text) and the GİB code lists bundled in the package.

What it writes

All MCP tools are read-only; the README says none of them writes files. ornek_fatura does not write a file either; it returns XML text.

Network

README: "no data goes over the network"; the check runs locally without contacting GİB. Only the package and SaxonC-HE are downloaded during installation. This is the README's claim.

The assistant side

Even though the tool stays offline, the file's contents and the tool's output become part of the chat, so the AI assistant you use sees them. Invoices contain the tax ID (VKN) or national ID number (TCKN), names and amounts. This part depends on your assistant's privacy settings, not on the tool.

Security check (October 15, 2026): GitHub Security Advisories is empty, there is no entry for efatura-kontrol in the GitHub Advisory Database or in OSV (PyPI), the PyPI page lists no known vulnerability, and the repository has no open or closed issues. No recorded advisory appears. That does not mean "safe": the project is three weeks old, has a single developer and 2 stars; its dependencies (lxml, saxonche, mcp) have their own records that should be checked separately.

Is efatura-kontrol free?

The software is free and MIT-licensed; the README and pyproject.toml mention no fee or plan. No account, API key or environment variable is needed (llms-install.md). Your AI assistant's own subscription is a separate matter, and the README says nothing about it.

Allowed

MIT: you may use, modify and distribute the code
Commercial use is allowed under the MIT license

Not allowed

The XSD, Schematron and code lists published by GİB are included in the package in derived form; the README does not state the terms of use for these files separately

Source: the README, pyproject.toml and the LICENSE file in the repository. This is not legal advice; if you plan to distribute it commercially, check the terms of the GİB files separately.

Turkey-specific: GİB rules and limits

The tool uses GİB's own files: the UBL-TR 1.2.1 Package and the e-Fatura Package (29), downloaded from ebelge.gib.gov.tr; the Schematron update is dated July 1, 2026 (KAYNAKLAR.md). According to the README the rules were not written by hand but generated from the GİB files with a script; only the Turkish explanations and the arithmetic checks are hand-written. If GİB's rules change, the tool is only updated with a new release.

In scope	Out of scope (README)
e-Fatura, e-Arşiv invoice, e-İrsaliye, waybill and application response, envelope	e-Arşiv report (`eArsivRaporu`) and e-Defter (e-ledger)
XSD, GİB Schematron, arithmetic, signature structure	Cryptographic verification of the signature (certificate, digest, timestamp)
Internal consistency of the document	GİB live checks: is the taxpayer registered, is the alias valid, is the number a duplicate

This page is not accounting, tax or legal advice. For whether an invoice complies with Turkish tax law, ask your accountant and your integrator. The tool is not an official GİB product; the README also states that it has no link to GİB.

Invoice XML files may contain personal data (first name, last name, TCKN). Before uploading this data to an AI assistant, consider your own data-controller obligations under KVKK (Turkey's Personal Data Protection Law); this is not legal advice.

Common problems and fixes

What happens	What to do
Long wait on first run, or the client times out	SaxonC-HE (~40 MB) downloads the first time and the Schematron takes ~0.5 s to compile (README). Run `uvx efatura-kontrol --version` in a terminal first (llms-install.md).
On Windows the client cannot find `uvx`	llms-install.md: put the full path of uvx.exe in the `command` field.
The `ornek_fatura` tool mentioned in the README is not in the list	CHANGELOG: this tool is [Unreleased]; it is not in 0.1.0 on PyPI. It will not be in the published version until a new release comes out.
The tool said "valid" but GİB or the integrator rejected it	README limits: no live GİB checks and no cryptographic signature verification; "valid" is no guarantee against additional server-side checks. Also read your integrator's own error message.
`uzak-dosya-kapali` error in remote mode	README: the file parameter is disabled in remote mode; send the document as text with the `xml` parameter. Remote mode may not be in the published version.

How do you uninstall efatura-kontrol?

MCP entry: Delete the efatura-kontrol entry from your client's MCP settings.
If you installed with pip: Remove the package with pip uninstall efatura-kontrol.

The README gives no uninstall steps; the steps above are the standard method. The README does not give a command for clearing the uvx cache.

Frequently asked questions

How do you check an e-Fatura XML file before sending it to GİB?

That is what efatura-kontrol was written for: it checks the XML on your own computer against the XSD and Schematron rules GİB publishes, plus arithmetic and signature structure. Use it from the command line with efatura-kontrol dogrula invoice.xml, or through MCP with an assistant. A "valid" result does not guarantee that GİB will accept the invoice.

What does an e-Fatura Schematron error mean?

Schematron is the rule set GİB applies to document content (e.g. a valid unit code, a withholding rate). For every Schematron finding, efatura-kontrol gives a code in the form sch-..., GİB's original message, the line number, an explanation in Turkish and a suggested fix; you can also look up the code with the bulgu_acikla tool.

Is efatura-kontrol an official GİB tool?

No. It is an MIT-licensed community project by a single developer (Berkant Acun); the README states it has no link to GİB. The project was opened on September 21, 2026, its only published version is 0.1.0 and it has 2 stars.

Do my invoices go to the internet?

The README says "no data goes over the network"; the check runs locally. However, the contents of the file you give your AI assistant and the tool's output become part of the chat, so the assistant sees that data.

Is efatura-kontrol free? Does it need an account or a key?

It is free and MIT-licensed. No account, API key or environment variable is needed. It requires Python 3.10+ and (if you use uvx) uv.

Does efatura-kontrol issue invoices or send them to GİB?

No. All tools are read-only; it does not send invoices, write files or connect to GİB. It only checks the XML you give it. The ornek_fatura tool in the README generates an unsigned sample XML for testing and learning only, and it is not in the published 0.1.0 release.

Related guides

Cline Borsa MCP e-Fatura MCP İhale MCP iyzico MCP (qwertyvan)iyzico MCP (seyithanalkan)

Sources

Not clear in the official sources: The gap between the published version and the README (number of tools, remote mode, Docker image) · whether the tool really stays offline (README claim only) · whether it works in Claude Code and Cursor (the README names them) · how closely it matches GİB's actual accept and reject decisions (no independent verification) · the redistribution terms of the GİB files. Each is covered in its section.