[BitFaktura.cz — Nápověda](https://napoveda.bitfaktura.cz/index.md) / [Integrace](https://napoveda.bitfaktura.cz/integrace.md) # [Integrace s AI asistenty (MCP) — Claude, ChatGPT a další](https://napoveda.bitfaktura.cz/integrace-s-ai-asistenty-mcp-claude-chatgpt-a-dalsi.md) 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? Chcete-li propojit AI asistenta s BitFakturou: 1. 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), 2. 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, ![Ekran nadania zgód do odczytu danych dla Claude Desktop.](523a5ddaac2a-MCP_komunikat_pozwolenie.png) 3. kliknij **Pozwól**, aby autoryzować dostęp albo **Odmów**, jeśli nie chcesz łączyć tego asystenta z kontem, 4. 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: 1. zaloguj się do Claude Desktop i otwórz ustawienia aplikacji **Settings > Connectors > Add custom connector**, ![Ustawienia AI z opcją dodania własnego konektora do połączenia z Fakturownią.](52dd1e25a79c-MCP_cloude_desktop_add-connectro.png) 2. 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, ![Formularz tworzenia własnego konektora z podaną nazwą i adresem mcp.](774fad4d48b8-MCP_add_cnnector.png) 3. kliknij **Add**, a następnie **Connect** - otworzy się przeglądarka z Fakturownią, ![Opcja nawiązania połączenia przez Claude Desktop z Fakturownią przez MCP.](6429c91759aa-MCP_connect.png) 4. jeśli system tego wymaga zaloguj się, a następnie zatwierdź dostęp na ekranie zgody, ![Ekran nadania zgód do odczytu danych dla Claude Desktop.](1990b6c8c5a1-MCP_komunikat_pozwolenie.png) 5. **gotowe** - asystent Claude Desktop ma dostęp do Twojej Fakturowni w trybie odczytu. Przykładowe zapytanie i odpowiedź wygenerowana bezpośrednio w Claude Desktop. ![Przykładowe zapytanie przez serwer MCP z poziomu Claude Desktop o podsumowanie faktur dla klienta.](25feaacf81d0-MCP_przykład_zapytania.png) ## 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): ```json { "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): ```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: ```json { "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: 1. po stronie Fakturowni przejdź do zakładki [**Ustawienia > Ustawienia konta > Integracja**](https://app.fakturownia.pl/goto?after_url=account/edit?tabs=6), ![Ustawienia konta w systemie Fakturownia z aktywną zakładką integracji.](beb373fa3395-STOPKA_FAKTURY_ustawienia.png) 2. w sekcji **Aplikacje AI** kliknij **Zarządzaj dostępem do aplikacji AI**, ![Ustawienia integracji w tym zarządzania dostępami aplikacji AI do Fakturowni.](5a428b159fab-MCP_aplikacje_AI.png) 3. zobaczysz listę aktywnych autoryzacji (nazwa aplikacji i data autoryzacji). Przy każdej z nich dostępna będzie opcja **Cofnij dostęp**. ![Lista aplikacji AI z dostępem do konta oraz opcją cofnięcia dostępu.](ec8291f43ffa-MCP_cofnij_dostęp.png) Dostęp możesz też odwołać bezpośrednio z ustawień samego klienta AI. ## Ważne informacje związane z MCP 1. Autoryzacja odbywa się przez standard OAuth 2.1 z PKCE - nigdy nie wklejasz ręcznie żadnego tokena API, logujesz się normalnie przez Fakturownię. 2. Dostęp jest zawsze związany z jednym, konkretnym kontem - token wydany dla jednego konta nie zadziała na innym. 3. 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. 4. 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.