Back to Browse

Uol MCP Server

Developer ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Invoices, receivables, VAT, ledger and documents from UOL Účetnictví (Czech online accounting)

About

Invoices, receivables, VAT, ledger and documents from UOL Účetnictví (Czech online accounting)

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (3 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: 4 highly-trusted packages.

5 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

env_vars

Check that this permission is expected for this type of plugin.

file_system

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Tenant name (https://firma.ucetnictvi.uol.cz → firma), a full https://….uol.cz URL, or demoOptional

Environment variable: UOL_TENANT

E-mail of the UOL user (not needed for demo)Optional

Environment variable: UOL_EMAIL

UOL API token from /api_tokens (not needed for demo)Required

Environment variable: UOL_TOKEN

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "uol-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "uol-mcp@0.7.0"
      ],
      "env": {
        "UOL_EMAIL": "your-uol-email-here",
        "UOL_TOKEN": "your-uol-token-here",
        "UOL_TENANT": "your-uol-tenant-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

uol-mcp

Model Context Protocol server for UOL Účetnictví — ask Claude, Cursor or any other MCP client about your bookkeeping: issued and received invoices, who owes you money, uploaded documents, contacts.

Unofficial. Not affiliated with or endorsed by UOL a.s. It talks to the public UOL REST API with your own API token.

Česky

Status: v0.6 — read-only by default, opt-in writes. What changed: CHANGELOG.md.

What it can do

ToolAnswers
get_business_snapshotHow the company is doing, in one call: this month vs last, VAT, receivables, documents to process, bank
get_financial_overviewRevenue, expenses and profit per month from the general ledger, largest accounts
get_vat_overviewVAT per filing period: to pay or excess deduction, due date, final or estimate
get_bank_balancesBank balances per account and currency (UOL keeps monthly snapshots)
get_companyCompany name, IČO, DIČ, address, VAT filing period; doubles as a connection check
search_sales_invoices, get_sales_invoiceIssued invoices with line items, VAT and payment status
search_purchase_invoices, get_purchase_invoiceReceived invoices
list_receivablesWho owes you, how much, how long overdue — totals per currency
export_sales_invoicePDF or ISDOC of an issued invoice, saved to disk (ISDOC is also returned as XML)
search_contacts, get_contactCustomers and suppliers by name, IČO or DIČ, with addresses and bank accounts
list_uploaded_documents, get_uploaded_document, download_uploaded_documentDocuments uploaded for the accountant, their state and files
list_codebookCurrencies, departments, contracts, price lists, own bank accounts, …
api_getRead-only GET of any other /v1/… endpoint

Example questions: "Jak si letos stojíme?", "Kolik zaplatím DPH za tento kvartál?", "Kdo mi dluží víc než 30 dní?", "Je faktura 2026000123 zaplacená?", "Na čem nejvíc utrácíme?", "Stáhni mi PDF poslední vydané faktury."

More read tools are available as opt-in toolsets (UOL_TOOLSETS): ledger (general-ledger postings, internal documents), banking (bank movements, petty-cash documents) and warehouse (products, stock levels, orders).

Ready-made prompts (slash commands in most clients): monthly_review, vat_check, overdue_followup (drafts reminders, sends nothing), process_inbox, and with write access issue_invoice (builds a sales invoice from your description, shows a dry run and creates a draft once you confirm). The uol://guide resource explains the domain to the model.

The uol-ucetnictvi skill goes further: Claude issues an invoice the way you always invoice that customer (DUZP rule, due days, products, line texts and bank account learned from your earlier invoices to them) and reads revenue, profit, VAT and receivables the way an accountant does (unbooked months, estimates, deadlines). Install it in Claude Desktop or claude.ai by zipping the skills/uol-ucetnictvi folder and uploading it under Settings → Capabilities → Skills, or in Claude Code by copying the folder to ~/.claude/skills/.

The server knows the API's quirks: invoice status valid means draft, payment status exists only for issued invoices, credit notes come with positive amounts, revenue and expenses have to be read from the ledger (excluding year-end closing entries), purchase invoices ignore issue-date filters, files have three different download shapes, and the rate limit (30 requests / 10 s) is respected client-side. See docs/DESIGN.md.

Getting an API token

  1. Open the API tokens page of your UOL tenant (path /api_tokens, e.g. https://firma.ucetnictvi.uol.cz/api_tokens) and create a token.
  2. The UOL user needs the REST API permission. A dedicated user with only the rights you want the assistant to have is a good idea.

Your tenant is the first part of your UOL address: https://firma.ucetnictvi.uol.cz → firma.

Want to try it first? UOL_TENANT=demo uses UOL's public DEMO company, no token needed.

Configuration

VariableMeaning
UOL_TENANTdemo, your tenant name (firma), a host prefix (firma.sandbox) or the full https://….uol.cz URL
UOL_EMAILE-mail you log into UOL with
UOL_TOKENAPI token
UOL_DOWNLOAD_DIRWhere exported and downloaded files go (default ~/Downloads/uol-mcp)
UOL_TOOLSETSComma-separated: core, insights (these two are the default), ledger, banking, warehouse, or all
UOL_ACCESSread (default), write or full — see Writing
UOL_PROMPT_LANGUAGELanguage of the prompts (slash commands) and of the answers they ask for: cs (default) or en
UOL_ACCOUNTS, UOL_DEFAULT_ACCOUNTSeveral companies in one server — see Several companies; UOL_ACCOUNT_<NAME>_ACCESS sets one account's level
UOL_PROFILES_FILEThe same from a JSON file
UOL_UPLOAD_DIRSFolders upload_document may read from (default ~/Downloads, ~/Desktop, ~/Documents; :-separated, ; on Windows). The HTTP server has no default: without this variable it accepts only content_base64
UOL_AUDIT_LOGFile that records every write as a JSON line
UOL_TIMEOUT_MSTimeout of one UOL request (default 30000)
UOL_DEBUG1 logs requests to stderr (never credentials)

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "uol": {
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": {
        "UOL_TENANT": "firma",
        "UOL_EMAIL": "you@example.com",
        "UOL_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

claude mcp add uol -e UOL_TENANT=firma -e UOL_EMAIL=you@example.com -e UOL_TOKEN=your-token -- npx -y uol-mcp

Cursor / VS Code

Cursor (.cursor/mcp.json) uses the same mcpServers block as Claude Desktop. VS Code (.vscode/mcp.json):

{
  "servers": {
    "uol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": { "UOL_TENANT": "firma", "UOL_EMAIL": "you@example.com", "UOL_TOKEN": "your-token" }
    }
  }
}

Docker

docker run -i --rm -e UOL_TENANT=firma -e UOL_EMAIL=you@example.com -e UOL_TOKEN=your-token -v "$HOME/Downloads/uol-mcp:/data" ghcr.io/jakubbegera/uol-mcp

Exported and downloaded files are written to /data inside the container; the -v mount keeps them. In an MCP client config, use docker as the command and the rest as args.

Claude Desktop extension

Each release ships uol-mcp.mcpb. Open it to install, then fill in tenant, e-mail and token in the form; the token is stored as a secret. bash scripts/build-mcpb.sh builds the bundle from source.

HTTP server (self-hosting)

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 32) UOL_TENANT=firma UOL_EMAIL=you@example.com UOL_TOKEN=your-token npx -y uol-mcp

The endpoint is http://127.0.0.1:3000/mcp (HOST, PORT to change; /health for probes). Two modes:

  • One tenant: UOL credentials in the server's env. Clients must send Authorization: Bearer <MCP_AUTH_TOKEN>; the server refuses to start without the token.
  • Pass-through: no UOL credentials in the env. Each client sends its own X-UOL-Tenant, X-UOL-Email and X-UOL-Token headers with every request; the server stores nothing. MCP_AUTH_TOKEN is optional on localhost.

Over HTTP, exported invoices and downloaded documents come back inside the tool result instead of being saved on the server, and upload_document takes the file as content_base64 — it reads no paths on the server unless UOL_UPLOAD_DIRS is set. In Docker, bind to all interfaces and publish the port: docker run -p 3000:3000 -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=… -e MCP_ALLOWED_HOSTS=mcp.example.com ….

VariableMeaning
MCP_TRANSPORThttp starts the HTTP server (same as --http)
HOST, PORTBind address, default 127.0.0.1:3000
MCP_AUTH_TOKENBearer token clients must send, at least 32 characters; required in one-tenant mode and whenever HOST is not a loopback address
MCP_ALLOWED_HOSTSAccepted Host names (comma-separated); required when HOST is not a loopback address
MCP_ALLOWED_ORIGINSBrowser origins allowed to call the endpoint (none by default)

The server speaks plain HTTP: anywhere beyond localhost, put it behind a reverse proxy that terminates TLS. The server refuses to start on a non-loopback address without MCP_AUTH_TOKEN and MCP_ALLOWED_HOSTS.

Check the setup

UOL_TENANT=firma UOL_EMAIL=you@example.com UOL_TOKEN=your-token npx -y uol-mcp doctor

Writing (opt-in)

With UOL_ACCESS=write these tools appear:

ToolDoes
upload_documentUploads a PDF to UOL's document inbox for the accountant (only from UOL_UPLOAD_DIRS)
create_sales_invoiceCreates an issued invoice for an existing contact — a draft unless issue: true; number sets the printed invoice number, otherwise UOL takes the next one from its number series
update_sales_invoiceChanges or issues a draft invoice, its number included (UOL doesn't allow editing issued ones)
create_purchase_invoiceBooks a received invoice from an existing supplier
create_contact, update_contactAdds or changes a customer / supplier (refuses a duplicate IČO)
create_payment_demandCreates a payment demand (upomínka) for unpaid invoices of one customer — never sends it
mark_document_processed, pair_uploaded_document, tag_uploaded_document, untag_uploaded_documentThe accountant's inbox: state, link to the booked record, tags

UOL_ACCESS=full adds delete_sales_invoice (drafts only), repair_sales_invoice (storno or back to draft for issued invoices) and api_request (a raw write to any endpoint).

Invoice lines need a UOL product (list_codebook with kind: products lists them). Every write supports dry_run (shows exactly what would be sent), creates are safe to retry (idempotency key), and the tools are marked so clients ask you before running them. Set UOL_AUDIT_LOG to keep a record of every write.

Several companies

Accountants with several clients on UOL can serve them all from one server. List the accounts in UOL_ACCOUNTS and give each one its own variables (name upper-cased, - becomes _):

"env": {
  "UOL_ACCOUNTS": "firma,novak",
  "UOL_ACCOUNT_FIRMA_TENANT": "firma",
  "UOL_ACCOUNT_FIRMA_EMAIL": "ja@firma.cz",
  "UOL_ACCOUNT_FIRMA_TOKEN": "op://Private/UOL firma/credential",
  "UOL_ACCOUNT_NOVAK_TENANT": "novak",
  "UOL_ACCOUNT_NOVAK_EMAIL": "ja@firma.cz",
  "UOL_ACCOUNT_NOVAK_TOKEN": "op://Private/UOL novak/credential",
  "UOL_ACCOUNT_NOVAK_LABEL": "Novák s.r.o."
}

The first account is the default (or set UOL_DEFAULT_ACCOUNT). With the 1Password CLI, start the server as op run -- node …/dist/index.js and the op:// references are replaced by the tokens at startup — nothing secret sits in the config. uol-mcp doctor checks every account.

Alternatively, point UOL_PROFILES_FILE at a JSON file:

{
  "default": "firma",
  "accounts": {
    "firma": { "tenant": "firma", "email": "ja@firma.cz", "token_env": "UOL_TOKEN_FIRMA" },
    "novak": { "tenant": "novak", "email": "ja@firma.cz", "token_env": "UOL_TOKEN_NOVAK", "label": "Novák s.r.o." }
  }
}

token_env names an environment variable holding the token, so the file needs no secrets (an inline token works too; keep such a file chmod 600). The server then offers list_accounts, and every tool takes an account argument — "Kdo dluží firmě Novák?" goes to the right tenant. Each account keeps its own rate limit.

Accounts can have their own access level: with UOL_ACCESS=write and UOL_ACCOUNT_NOVAK_ACCESS=read (or "access": "read" in the profiles file), writes to Novák are refused while the other account can still write. list_accounts shows each account's level.

Privacy and safety

  • Read-only unless you set UOL_ACCESS=write. Text inside invoices, notes and documents is treated as data: review what the assistant proposes to write before you approve it.
  • Whatever the tools return goes to the AI model your client uses. Accounting data contains personal data of your contacts and employees — use a plan whose terms you are comfortable with.
  • Credentials are used only for https://*.uol.cz and are never written to logs or tool output.
  • Downloaded files are saved under UOL_DOWNLOAD_DIR only, readable by the owner, and never replace an existing file (a taken name gets a (1) suffix). Downloads over 50 MB are refused.
  • The model is told that text coming from UOL (invoices, notes, documents) is data, never instructions.

From source

Requires Node.js 22+.

git clone https://github.com/jakubbegera/uol-mcp.git
cd uol-mcp
npm install
npm run build

Then point your client at node /path/to/uol-mcp/dist/index.js instead of npx -y uol-mcp.

Development

npm test                 # unit + MCP-level tests against recorded DEMO responses
npm run typecheck
npm run smoke            # calls every tool against the live DEMO tenant
npm run record-fixtures  # refreshes test/fixtures/demo from the DEMO tenant
bash scripts/build-mcpb.sh  # builds build/uol-mcp.mcpb
docker build -t uol-mcp .

CI runs the type check, tests, npm audit, a Trivy scan of the Docker image, CodeQL and, on pull requests, dependency review; Dependabot keeps dependencies, actions and the base image current.

Releases are cut by pushing a v* tag; after a maintainer approves the release environment, .github/workflows/release.yml publishes to npm, GHCR, the GitHub release (MCPB bundle) and the MCP Registry.

Design notes, API facts and the roadmap are in docs/DESIGN.md.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Report security problems privately as described in SECURITY.md.

License

MIT

Reviews

No reviews yet

Be the first to review this server!