Integrace BitFaktury s AI asistentem přes MCP

BitFaktura podporuje protokol MCP (Model Context Protocol) - standard, který umožňuje AI asistentům (např. Claude Desktop, ChatGPT Desktop, Codex) bezpečně číst data z vašeho účtu a odpovídat na dotazy o fakturách a klientech bez nutnosti ručně vkládat data nebo API tokeny.

Co může AI asistent udělat

Po propojení může AI asistent vaším jménem:

vyhledávat faktury - podle čísla, názvu odběratele, klienta, stavu (vystavená / odeslaná / zaplacená / částečně zaplacená / odmítnutá), typu dokladu (DPH faktura, proforma, opravný doklad, účtenka, zálohová/závěrečná faktura) a časového rozmezí, zvlášť pro prodeje a nákupy,
zjišťovat údaje o klientovi - kontaktní údaje, adresu, IČO/DIČ, číslo bankovního účtu a počet souvisejících faktur (podle ID klienta),
zjišťovat vyúčtování s klientem - kolik klient zaplatil, kolik zbývá doplatit, v členění podle měn a časového rozmezí.

Příklady dotazů, které můžete asistentovi po propojení položit: “Jaké faktury jsem vystavil/a firmě X tento měsíc?”, “Kolik nám tato firma ještě dluží?”, “Uveď IČO a adresu klienta s ID 123”.

UPOZORNĚNÍ! Integrace funguje pouze v režimu čtení - AI asistent nemůže vystavovat, upravovat ani mazat faktury, klienty ani žádná jiná data na účtu.

Co je potřeba k používání MCP?

Pro využití BitFaktura MCP potřebujete:

účet v BitFaktuře a přístup k účtu, který chcete propojit, v roli vlastníka účtu
AI klienta podporujícího vzdálené MCP servery přes HTTP a autorizaci OAuth 2.0,
adresu vašeho účtu BitFaktura - je to adresa, pod kterou se přihlašujete ke svému účtu v prohlížeči, např. https://vas-ucet.bitfaktura.cz. Tuto adresu budete potřebovat k vytvoření adresy MCP serveru.

UPOZORNĚNÍ!! Propojení přes MCP může provést pouze uživatel s rolí majitele účtu.

Jak propojit AI asistenta s BitFakturou?

Jak připojit AI asistenta k BitFaktuře?

Pro připojení AI asistenta k BitFaktuře:

v nastavení svého AI klienta (np. Claude Desktop) přidejte nový MCP server, se zadáním adresy https://tvuj-nazev.bitfaktura.cz/mcp (nahraďte tvuj-nazev prefixem svého účtu - stejným, který vidíte v adrese prohlížeče, když jste přihlášeni do BitFaktury),
při prvním připojení AI klient otevře v prohlížeči přihlašovací obrazovku BitFaktury (pokud nejste přihlášeni), a následně obrazovku se souhlasem - uvidíte název AI aplikace a seznam funkcí, ke kterým žádá o přístup,
klikněte na Povolit, chcete-li přístup autorizovat, nebo na Odmítnout, pokud tohoto asistenta k účtu připojit nechcete,
od této chvíle může AI asistent odpovídat na dotazy s využitím dat z vašeho účtu - bez nutnosti opětovného přihlašování (dokud přístup nezrušíte).

Jak připojit AI asistenta k BitFaktuře - Claude Desktop?

Pro integraci BitFaktury a Claude Desktop:

přihlaste se do Claude Desktop a otevřete nastavení aplikace Settings > Connectors > Add custom connector,
vyplňte pole:
- název konektoru: BitFaktura (nebo jiný název, který budete vidět v aplikaci),
- Remote MCP server URL: https://tvuj-ukazkovy-ucet.bitfaktura.cz/mcp, kde za tvuj-ukazkovy-ucet vložíte prefix svého účtu,
klikněte na Add, a poté na Connect - otevře se prohlížeč s BitFakturou,
pokud to systém vyžaduje přihlaste se, a poté potvrďte přístup na obrazovce se souhlasem,
hotovo - asistent Claude Desktop má přístup k vaší BitFaktuře v režimu pouze pro čtení.

Jak připojit AI asistenta k BitFaktuře - Claude Code?

Přidejte server (adresu nahraďte svou):

claude mcp add BitFaktura –transport http https://tvuj-ucet.bitfaktura.cz/mcp

Ve výchozím nastavení je server uložen pro aktuální projekt (–scope local). Aby byl dostupný ve všech projektech, přidejte –scope user:

claude mcp add BitFaktura –transport http –scope user https://acme.bitfaktura.cz/mcp

Přihlaste se (autorizace OAuth). V Claude Code spusťte:

/mcp

Vyberte BitFaktura a potvrďte přihlášení, otevře se prohlížeč s BitFakturou. Přihlaste se (pokud je třeba) a potvrďte přístup na obrazovce se souhlasem.

Hotovo. Zeptejte se např.:

Zobraz 5 posledních neuhrazených faktur.

Alternativně místo příkazu můžete přidat záznam do konfiguračního souboru klienta (np. .mcp.json v adresáři projektu nebo claude_desktop_config.json v Claude Desktop):

{
  "mcpServers": {
    "BitFaktura": {
      "type": "http",
      "url": "https://acme.bitfaktura.cz/mcp"
    }
  }
}

Autorizaci OAuth i tak provedete přes /mcp po přidání záznamu.

Jak připojit AI asistenta k BitFaktuře - Codex?

Přidejte server (adresu nahraďte svou):

codex mcp add –url https://tvuj-ucet.bitfaktura.cz/mcp BitFaktura

Záznam se uloží do ~/.codex/config.toml, soubor nemusíte upravovat ručně.

Přihlaste se (autorizace OAuth):

codex mcp login BitFaktura

Otevře se prohlížeč s BitFakturou, přihlaste se a potvrďte přístup. Codex sám obslouží návrat (naslouchá na lokálním portu).

Hotovo. Zeptejte se na svá data.

Alternativně můžete záznam dopsat ručně do ~/.codex/config.toml (Codex používá formát TOML):

[mcp_servers.BitFaktura]
url = "https://acme.bitfaktura.cz/mcp"

a následně se přihlásit přes codex mcp login BitFaktura.

Jak připojit AI asistenta k BitFaktuře - jiný klient (jakýkoliv)?

BitFaktura MCP funguje s jakýmkoliv klientem podporujícím vzdálený MCP server přes Streamable HTTP a OAuth 2.0. Zadejte jen adresu serveru: https://.bitfaktura.cz/mcp.

Většina klientů přijímá záznam ve formátu JSON ve svém konfiguračním souboru:

{
  "mcpServers": {
    "BitFaktura": {
      "type": "http",
      "url": "https://acme.bitfaktura.cz/mcp"
    }
  }
}

Nemusíte zakládat žádnou aplikaci ani přepisovat client_id či secrety. Klient se registruje automaticky (Dynamic Client Registration), a přístup získáte přihlášením přes OAuth v prohlížeči.

Co, pokud mám v BitFaktuře více účtů?

Přístup je přiřazen k jednomu, konkrétnímu účtu (subdoméně). Pokud chcete, aby AI asistent měl přístup k několika vašim účtům, přidejte v AI klientovi samostatný záznam pro každý z nich, np.:

{
“mcpServers”: {
“BitFaktura - Firma A”: { “type”: “http”, “url”: “https://firma-a.bitfaktura.cz/mcp” },
“BitFaktura - Firma B”: { “type”: “http”, “url”: “https://firma-b.bitfaktura.cz/mcp” }
}
}

Jak zrušit přístup AI aplikace?

Můžete kdykoli zkontrolovat, které AI aplikace mají přístup k vašemu účtu, a tento přístup odvolat:

na straně BitFaktury přejděte do záložky Nastavení > Nastavení účtu > Integrace,
v sekci AI aplikace klikněte na Správa přístupu AI aplikací,
zobrazí se seznam aktivních autorizací (název aplikace a datum autorizace). U každé z nich bude dostupná možnost Zrušit přístup.
Přístup můžete také zrušit přímo z nastavení samotného AI klienta.

Důležité informace týkající se MCP

Autorizace probíhá přes standard OAuth 2.1 s PKCE - nikdy nevkládáte ručně žádný token API, přihlašujete se normálně přes BitFakturu.
Přístup je vždy vázán na jeden, konkrétní účet - token vydaný pro jeden účet nebude funkční na jiném.
Dotazy AI asistenta fungují na připojení pouze pro čtení, s časovým limitem provedení - asistent nemůže upravit ani přetížit databázi.
Přístup je plně vratný a viditelný - kdykoli zjistíte, kdo má přístup, a můžete jej zrušit.

Nejčastější problémy a řešení

❓Prohlížeč se neotevřel nebo se přihlášení nedokončí. Spusťte přihlašování znovu (/mcp v Claude Code, codex mcp login v Codex). Ujistěte se, že jste přihlášeni ke správnému účtu BitFaktury v tomtéž prohlížeči.

❓„Chybí přístup k účtu” nebo chyba po potvrzení. Váš přihlášený uživatel musí mít přístup k účtu z adresy, kterou připojujete. Zkontrolujte, zda prefix v adrese …/mcp odpovídá správné firmě.

❓Asistent nevidí nástroje nebo server je „failed”. Zkontrolujte adresu serveru (musí končit na /mcp) a připojení. V Claude Code najdete stav a možnost opětovného připojení v panelu /mcp.

❓Odpověď je prázdná nebo „nenalezeno”. Upřesněte dotaz (np. rozsah dat, status, měnu). Pamatujte, že výsledky jsou omezeny na připojený účet a na data čitelná prostřednictvím tří dostupných nástrojů.

Zdroje