[Fakturownia - Baza wiedzy](https://pomoc.fakturownia.pl/index.md) / [Integracje i dodatki](https://pomoc.fakturownia.pl/integracje-i-dodatki.md) # [Integracja z asystentami AI (MCP) — Claude, ChatGPT i inne](https://pomoc.fakturownia.pl/integracja-z-asystentami-ai-mcp-claude-chatgpt-i-inne.md) Fakturownia obsługuje protokół MCP (Model Context Protocol) - standard, który pozwala asystentom AI (np. Claude Desktop, ChatGPT Desktop, Codex) bezpiecznie odczytywać dane z Twojego konta i odpowiadać na pytania o faktury i klientów bez konieczności ręcznego wklejania danych czy tokenów API. ## Co asystent AI może zrobić Po połączeniu asystent AI może w Twoim imieniu: - **wyszukiwać faktury** - po numerze, nazwie nabywcy, kliencie, statusie (wystawiona/ wysłana/ zapłacona/ częściowo zapłacona/ odrzucona), rodzaju dokumentu (VAT, proforma, korekta, rachunek, faktura zaliczkowa/końcowa) oraz zakresie dat, osobno dla sprzedaży i zakupów, - **sprawdzać dane klienta** - dane kontaktowe, adres, NIP, numer konta bankowego i liczbę powiązanych faktur (po ID klienta), - **sprawdzać rozliczenia z klientem** - ile klient zapłacił, ile zostało do zapłaty, z podziałem na waluty i zakres dat. Przykładowe pytania, które możesz zadać asystentowi po podłączeniu: „Jakie faktury wystawiłem firmie X w tym miesiącu?”, „Ile ta firma jest nam jeszcze winna?”, „Podaj NIP i adres klienta o ID 123”.
UWAGA! Integracja działa tylko w trybie odczytu - asystent AI nie może wystawiać, edytować ani usuwać faktur, klientów czy żadnych innych danych na koncie.
Zasady korzystania z usługi MCP określa [**regulamin usługi MCP**](https://fakturownia.pl/regulamin-mcp). ## Co jest wymagane do korzystania z MCP? Aby skorzystać z Fakturownia MCP, potrzebujesz: - **konta w Fakturowni** oraz dostępu do konta, które chcesz podłączyć w [**roli właściciela konta**](https://pomoc.fakturownia.pl/117735676-jak-dodac-nowego-uzytkownika-do-swojego-konta#domylne-role-systemowe-oraz-edycja-i-zmiana-roli-istniejcego-uytkownika), - **klienta AI obsługującego zdalne serwery MCP przez HTTP oraz autoryzację OAuth 2.1 z PKCE**, - **adresu swojego konta Fakturowni** - jest to adres, pod którym logujesz się do swojego konta w przeglądarce, np. https://twoje-przykladowe-konto.fakturownia.pl. Ten adres będzie potrzebny do utworzenia adresu serwera MCP.
UWAGA! Połączenie przez MCP może wykonać wyłącznie użytkownik z rolą właściciela konta.
## Jak połączyć asystenta AI z Fakturownią? Aby połączyć asystenta AI z Fakturownią: 1. w ustawieniach swojego klienta AI (np. Claude Desktop) dodaj nowy serwer MCP, wskazując adres https://twoja-nazwa.fakturownia.pl/mcp (zamień twoja-nazwa na prefiks swojego konta - ten sam, który widzisz w adresie przeglądarki, gdy jesteś zalogowany do Fakturowni), 2. przy pierwszym połączeniu klient AI otworzy w przeglądarce ekran logowania do Fakturowni (jeśli nie jesteś zalogowany), a następnie ekran zgody - zobaczysz nazwę aplikacji AI i listę funkcji, do których prosi o dostęp, ![Komunikat autoryzacyjny przy nadawaniu dostępu dla agenta AI do danych w Fakturowni.](1df5978b2570-MCP_komunikat_autoryzacja.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, ![Komunikat autoryzacyjny przy nadawaniu dostępu dla agenta AI do danych w Fakturowni.](2a0d8d8924b4-MCP_komunikat_autoryzacja.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. --- ## Powiązane - [Token API z uprawnieniami tylko do odczytu - czy można ograniczyć uprawnienia API?](https://pomoc.fakturownia.pl/token-api-z-uprawnieniami-tylko-do-odcytu-cy-mozna-ogranicyc-uprawnienia-api.md) - [Dodatkowe moduły Intum](https://pomoc.fakturownia.pl/dodatkowe-moduly-intum.md) - [Jak połączyć Fakturownię z KSeF 2.0 – Uwierzytelnienie automatyczne integracji - certyfikaty generowane w KSeF przez Fakturownię](https://pomoc.fakturownia.pl/200856394-jak-polaczyc-fakturownie-z-ksef-2-0-uwierzytelnienie-automatyczne-integracji-certyfikaty-generowane-w-ksef-przez-fakturownie.md) - [Jak połączyć Fakturownię z KSeF 2.0 - Uwierzytelnienie manualne – wgranie certyfikatów (uwierzytelniający i offline) z KSeF do Fakturowni](https://pomoc.fakturownia.pl/200350226-jak-polaczyc-fakturownie-z-ksef-2-0-uwierzytelnienie-manualne-wgranie-certyfikatow-uwierzytelniajacy-i-offline-z-ksef-do-fakturowni.md) - [E-Paragony w Fakturowni](https://pomoc.fakturownia.pl/179433040-e-paragony-w-fakturowni.md) - [Jak dodać numer faktury do stopki wydruku?](https://pomoc.fakturownia.pl/9199801-numer-faktury-w-stopce-wydruku-przy-numerach-stron.md) - [Jak zarządzać numeracją stron na wydrukach w Fakturowni?](https://pomoc.fakturownia.pl/902488-numeracja-stron-dokumentu.md) - [Skąd pobrać kod autoryzacyjny API?](https://pomoc.fakturownia.pl/150728-skad-pobrac-kod-autoryzacyjny-api.md)