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”.
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.
Jak propojit AI asistenta s BitFakturou?
Chcete-li propojit AI asistenta s BitFakturou:
- v nastavení svého AI klienta (např. Claude Desktop) přidejte nový MCP server, přičemž zadejte adresu https://vase-jmeno.bitfaktura.cz/mcp (nahraďte vase-jmeno prefixem svého účtu - stejným, jaký 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 poté obrazovku se souhlasem - uvidíte název AI aplikace a seznam funkcí, ke kterým žádá o přístup, klikněte na Povolit pro autorizaci přístupu,
- kliknij Pozwól, aby autoryzować dostęp albo Odmów, jeśli nie chcesz łączyć tego asystenta z kontem,
- od tej pory asystent AI może odpowiadać na pytania korzystające z danych Twojego konta - bez konieczności ponownego logowania (dopóki nie cofniesz dostępu).
Jak połączyć asystenta AI z Fakturownią - Claude Desktop?
Aby zintegrować Fakturownię i Claude Desktop:
- zaloguj się do Claude Desktop i otwórz ustawienia aplikacji Settings > Connectors > Add custom connector,
- wypełnij pola:
- nazwa konektora: Fakturownia (lub inna nazwa, którą będziesz widział w aplikacji),
-
Remote MCP server URL: https://twoje-przykladowe-konto.fakturownia.pl/mcp, gdzie za twoje-przykladowe-konto wstaw swój prefiks konta,
- kliknij Add, a następnie Connect - otworzy się przeglądarka z Fakturownią,
- jeśli system tego wymaga zaloguj się, a następnie zatwierdź dostęp na ekranie zgody,
- gotowe - asystent Claude Desktop ma dostęp do Twojej Fakturowni w trybie odczytu.
Przykładowe zapytanie i odpowiedź wygenerowana bezpośrednio w Claude Desktop.
Jak połączyć asystenta AI z Fakturownią - Claude Code?
Dodaj serwer (podmień adres na swój):
claude mcp add Fakturownia –transport http https://twoje-konto.fakturownia.pl/mcp
Domyślnie serwer jest zapisany dla bieżącego projektu (–scope local). Aby był dostępny we wszystkich projektach, dodaj –scope user:
claude mcp add Fakturownia –transport http –scope user https://acme.fakturownia.pl/mcp
Zaloguj się (autoryzacja OAuth). W Claude Code uruchom:
/mcp
Wybierz Fakturownia i potwierdź logowanie, otworzy się przeglądarka z Fakturownią. Zaloguj się (jeśli trzeba) i zatwierdź dostęp na ekranie zgody.
Gotowe. Zapytaj np.:
Pokaż 5 ostatnich nieopłaconych faktur.
Alternatywnie zamiast komendy możesz dodać wpis do pliku konfiguracji klienta (np. .mcp.json w katalogu projektu albo claude_desktop_config.json w Claude Desktop):
{
"mcpServers": {
"Fakturownia": {
"type": "http",
"url": "https://acme.fakturownia.pl/mcp"
}
}
}
Autoryzację OAuth i tak przeprowadzasz przez /mcp po dodaniu wpisu.
Jak połączyć asystenta AI z Fakturownią - Codex?
Dodaj serwer (podmień adres na swój):
codex mcp add –url https://twoje-konto.fakturownia.pl/mcp Fakturownia
Wpis trafia do ~/.codex/config.toml, nie musisz edytować pliku ręcznie.
Zaloguj się (autoryzacja OAuth):
codex mcp login Fakturownia
Otworzy się przeglądarka z Fakturownią, zaloguj się i zatwierdź dostęp. Codex sam obsłuży powrót (nasłuchuje na lokalnym porcie).
Gotowe. Zapytaj o swoje dane.
Alternatywnie możesz dopisać wpis ręcznie do ~/.codex/config.toml (Codex używa formatu TOML):
[mcp_servers.Fakturownia]
url = "https://acme.fakturownia.pl/mcp"
a następnie zalogować się przez codex mcp login Fakturownia.
Jak połączyć asystenta AI z Fakturownią - inny klient (dowolny)?
Fakturownia MCP działa z każdym klientem obsługującym zdalny serwer MCP przez Streamable HTTP i OAuth 2.0. Podaj tylko adres serwera: https://.fakturownia.pl/mcp.
Większość klientów przyjmuje wpis w formacie JSON w swoim pliku konfiguracji:
{
"mcpServers": {
"Fakturownia": {
"type": "http",
"url": "https://acme.fakturownia.pl/mcp"
}
}
}
Nie musisz zakładać żadnej aplikacji ani przepisywać client_id czy sekretów. Klient rejestruje się automatycznie (Dynamic Client Registration), a dostęp uzyskujesz przez logowanie OAuth w przeglądarce.
Co, jeśli w Fakturowni mam kilka kont?
Dostęp jest przypisany do jednego, konkretnego konta (subdomeny). Jeśli chcesz, aby asystent AI miał dostęp do kilku Twoich kont, dodaj w kliencie AI osobny wpis dla każdego z nich, np.:
{
“mcpServers”: {
“Fakturownia - Firma A”: { “type”: “http”, “url”: “https://firma-a.fakturownia.pl/mcp” },
“Fakturownia - Firma B”: { “type”: “http”, “url”: “https://firma-b.fakturownia.pl/mcp” }
}
}
Jak cofnąć dostęp aplikacji AI?
Możesz w każdej chwili sprawdzić, które aplikacje AI mają dostęp do Twojego konta, i odwołać ten dostęp:
- po stronie Fakturowni przejdź do zakładki Ustawienia > Ustawienia konta > Integracja,
- w sekcji Aplikacje AI kliknij Zarządzaj dostępem do aplikacji AI,
- zobaczysz listę aktywnych autoryzacji (nazwa aplikacji i data autoryzacji). Przy każdej z nich dostępna będzie opcja Cofnij dostęp.
Dostęp możesz też odwołać bezpośrednio z ustawień samego klienta AI.
Ważne informacje związane z MCP
- Autoryzacja odbywa się przez standard OAuth 2.1 z PKCE - nigdy nie wklejasz ręcznie żadnego tokena API, logujesz się normalnie przez Fakturownię.
- Dostęp jest zawsze związany z jednym, konkretnym kontem - token wydany dla jednego konta nie zadziała na innym.
- Zapytania asystenta AI działają na połączeniu tylko do odczytu, z limitem czasu wykonania - asystent nie może zmodyfikować ani przeciążyć bazy danych.
- Dostęp jest w pełni odwracalny i widoczny - w każdej chwili sprawdzisz, kto ma dostęp, i możesz go cofnąć.
Najczęstsze problemy i rozwiązania
❓Przeglądarka nie otworzyła się lub logowanie się nie kończy. Uruchom logowanie ponownie (/mcp w Claude Code, codex mcp login w Codex). Upewnij się, że jesteś zalogowany do właściwego konta Fakturowni w tej samej przeglądarce.
❓„Brak dostępu do konta” lub błąd po zatwierdzeniu. Twój zalogowany użytkownik musi mieć dostęp do konta z adresu, który podłączasz. Sprawdź, czy prefiks w adresie …/mcp odpowiada właściwej firmie.
❓Asystent nie widzi narzędzi lub serwer „failed”. Sprawdź adres serwera (musi kończyć się na /mcp) i połączenie. W Claude Code status i ponowne łączenie znajdziesz w panelu /mcp.
❓Odpowiedź jest pusta lub „nie znaleziono”. Doprecyzuj pytanie (np. zakres dat, status, waluta). Pamiętaj, że wyniki są ograniczone do podłączonego konta i do danych odczytywalnych przez trzy dostępne narzędzia.