Przejdź do treści

SaldeoSMART MCP

CI License: MIT Python 3.10+ mypy: strict

Serwer Model Context Protocol udostępniający REST API SaldeoSMART jako typowane, przyjazne LLM narzędzia. Odczyt dokumentów, faktur, kontrahentów, pracowników, wyciągów bankowych; tworzenie, aktualizacja, scalanie i synchronizacja danych księgowych — z dowolnego klienta zgodnego z MCP (Claude Desktop, Claude Code, Cursor, Zed, MCP Inspector lub własny SDK).

  • Szybki start

    Uruchom serwer w Dockerze, podłącz Claude Desktop i wykonaj pierwsze wywołanie narzędzia w pięć minut.

    Zacznij

  • Przewodniki

    Instalacja przez uvx lub Docker, konfiguracja każdego klienta MCP, diagnostyka uwierzytelniania, dodawanie nowego narzędzia.

    Przeglądaj

  • Dokumentacja API

    Generowany automatycznie katalog narzędzi MCP, modeli wejścia/wyjścia, kodów błędów, konfiguracji oraz wersji REST API SaldeoSMART.

    Referencje

  • Koncepcje

    Dlaczego FastMCP, jak działa podpisywanie żądań, model współbieżności i podejście do bezpieczeństwa.

    Więcej

Po co to powstało

Biura rachunkowe i ich klienci spędzają dużo czasu na czynnościach mechanicznych — przekazywaniu dokumentów, uzgadnianiu kontrahentów, oznaczaniu wymiarów, synchronizacji deklaracji podatkowych. SaldeoSMART udostępnia kompletne REST API dla tych operacji, ale ręczne podłączenie LLM do tego API jest żmudne i podatne na błędy (podpisywane żądania, payloady XML w gzip+base64, błędy per element w batchu). Ten serwer to ten cały kabel zrobiony raz, dobrze: każdy udokumentowany endpoint jest dostępny jako typowane narzędzie MCP z docstringiem, na podstawie którego LLM może działać.

Najważniejsze cechy

  • 43 narzędzia — każdy udokumentowany endpoint REST SaldeoSMART, pogrupowany według dziedziny.
  • Prywatność — tokeny SecretStr, redakcja URL-i w logach, blokada równoległych żądań.
  • Ścisłe typowanie — modele Pydantic v2, CI z mypy strict.
  • Polski + English — pełna dwujęzyczna dokumentacja (ta strona).
  • Licencja MIT, projekt nie jest powiązany z SaldeoSMART/BrainShare.

W skrócie

# Uruchomienie w Dockerze
docker run --rm -i \
  -e SALDEO_USERNAME=twój-login \
  -e SALDEO_API_TOKEN=twój-token \
  ghcr.io/piotrlinski/saldeosmart-mcp:latest

# Lub przez uvx (bez demona Dockera)
uvx saldeosmart-mcp \
  --username twój-login \
  --api-token twój-token

Następnie wskaż klientowi MCP powyższe polecenie. Pełna konfiguracja: Konfiguracja Claude Desktop.

Uwaga — narzędzia zapisu modyfikują dane księgowe

Każde narzędzie merge_*, add_*, update_*, delete_*, recognize_*, sync_* i create_* zmienia dane na koncie klienta. Zanim udostępnisz je autonomicznemu agentowi, przejrzyj katalog narzędzi.

Strony referencyjne pozostają w języku angielskim

Katalog narzędzi, modeli, kodów błędów i wersji API jest generowany z docstringów w kodzie źródłowym (po angielsku), aby zachować spójność z kontraktem narzędzi MCP. Strony przewodników, samouczków i koncepcji są tłumaczone na polski.