Skip to content

SaldeoSMART MCP

CI License: MIT Python 3.10+ mypy: strict

A Model Context Protocol server that exposes the SaldeoSMART REST API as a set of typed, LLM-friendly tools. Read documents, invoices, contractors, employees, bank statements; create, update, merge, and synchronize accounting records — from any MCP-aware client (Claude Desktop, Claude Code, Cursor, Zed, MCP Inspector, or your own SDK harness).

  • Quickstart

    Run the server in Docker, point Claude Desktop at it, and make your first tool call in five minutes.

    Get started

  • How-to guides

    Install with uvx or Docker, configure each MCP client, debug authentication, add a new tool wrapping a Saldeo endpoint.

    Browse guides

  • Reference

    Auto-generated catalog of every MCP tool, every input/output model, error codes, configuration, and the Saldeo API-version matrix.

    API reference

  • Explanation

    Why FastMCP over a custom transport, how request signing works, the threading model, and the security posture.

    Concepts

Why this exists

Accounting firms and their clients spend a lot of time on plumbing — moving documents, reconciling contractors, tagging dimensions, syncing tax declarations. SaldeoSMART has a comprehensive REST API for all of it, but wiring an LLM to that API by hand is tedious and error-prone (signed requests, gzip+base64 XML payloads, per-item batch errors). This server is the wiring done once, well: every documented endpoint is exposed as a typed MCP tool with a docstring an LLM can act on.

Highlights

  • 43 tools — every documented SaldeoSMART REST endpoint, grouped by domain.
  • Privacy-first — SecretStr tokens, URL redaction in logs, single-flight request lock.
  • Strict typing — Pydantic v2 models for every input/output, mypy-strict CI.
  • Polski + English — full bilingual documentation (this site).
  • MIT-licensed, not affiliated with SaldeoSMART/BrainShare.

At a glance

# Run with Docker
docker run --rm -i \
  -e SALDEO_USERNAME=your-login \
  -e SALDEO_API_TOKEN=your-token \
  ghcr.io/piotrlinski/saldeosmart-mcp:latest

# Or via uvx (no Docker daemon)
uvx saldeosmart-mcp \
  --username your-login \
  --api-token your-token

Then point your MCP client at the command above. See Configure Claude Desktop for a complete config snippet.

Heads-up — write tools mutate live accounting data

Every merge_*, add_*, update_*, delete_*, recognize_*, and sync_* tool changes data on the customer's account. Read the tool catalog before letting an agent autonomously call write tools.