iDoklad

io.github.honzsikPublished by GitHub account honzsikv0.4.0Updated Nov 11, 2026

Unofficial iDoklad invoicing: read and create invoices, proformas, credit notes and contacts.

The publisher's own server: Doklad.ai

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Unofficial iDoklad server that lets an assistant read, create and email Czech/Slovak invoices, proformas, credit notes and contacts.

What you can do
  • List and inspect issued, proforma, credit-note and received invoices, and save their PDFs
  • Create invoices, proformas, final invoices from proformas and credit notes, and mark documents paid or unpaid
  • Email invoices, payment reminders and payment confirmations through iDoklad templates
  • Review business stats, top partners and per-customer payment behaviour
  • Search contacts and price-list items, and create contacts
  • Look up codebooks, search the bundled API reference, or call any iDoklad endpoint directly
When to use it
Useful when you keep books in iDoklad and want an assistant to answer questions about overdue or unpaid invoices, revenue and VAT, or to draft and send invoices and reminders without leaving the chat.
Requirements
Runs locally via npx or the Claude Desktop extension; needs Node.js 22 or newer and an iDoklad plan with API access (Oblíbený or Prémiový). Requires IDOKLAD_CLIENT_ID and IDOKLAD_CLIENT_SECRET from iDoklad Settings → API, plus IDOKLAD_APPLICATION_ID from a ClientCredentials app on the iDoklad developer portal. Optional IDOKLAD_DOWNLOAD_DIR and IDOKLAD_READ_ONLY.
Before you install
The server is unofficial and in early development, so tools may change. It holds the IDOKLAD_CLIENT_SECRET, which should be treated like a password and never committed or pasted into chat. Read-only by default; setting IDOKLAD_READ_ONLY=false enables tools that create documents, record payments and send emails to customers. Invoice and contact data read from iDoklad is passed to the AI model. Use a test company for write experiments.

Installation

In SourceWeft

  1. Open iDoklad in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

idoklad-mcp

[CI] [License: MIT]

An unofficial MCP server for iDoklad, the Czech and Slovak online invoicing service. It lets Claude, Codex, Cursor and other AI assistants read and create invoices in your iDoklad account.

[!NOTE] This project is not affiliated with or endorsed by iDoklad or Seyfor, a. s. 🇨🇿 Návod v češtině

[!WARNING] Early development (v0.4). Tools and their inputs may still change. See the roadmap.

What you can ask

  • "Which invoices are overdue?"
  • "How much has ACME paid us this year?"
  • "Download the PDF of the last invoice for Globex."
  • "Which received invoices haven't we paid yet?"
  • "Kdo mi dluží nejvíc?" / "Jak se mi letos daří oproti loňsku?"
  • "Kolik mi zbývá do povinné registrace k DPH?"
  • "Create an invoice for ACME s.r.o.: 10 hours of consulting at 1,500 CZK, due in 14 days." (needs write mode)
  • "Invoice Globex like last month, but for 42 hours." (copies currency, VAT and language from the previous invoice)
  • "Mark invoice 20260018 as paid today."
  • "Send payment reminders for all overdue invoices."
  • "Issue a credit note for invoice 20260015, the client returned 2 of the 10 licences."

Requirements

  • An iDoklad plan that includes API access: Oblíbený (Popular) or Prémiový (Premium). The Free and Basic plans have no API.
  • Node.js 22 or newer.
  • An MCP client: Claude Desktop, Claude Code, Codex, Cursor, VS Code or similar.

Setup

1. Get your credentials

You need three values. They take about five minutes to get.

Client ID and Client Secret, from iDoklad:

  1. Sign in to app.idoklad.cz.
  2. Go to Nastavení (Settings) → API.
  3. Copy the Client ID and Client Secret.

These belong to one company (agenda) and one user.

Application ID, from the iDoklad developer portal:

  1. Create an account at developer.idoklad.cz.
  2. Under Nová aplikace, enter any name and set Flow to ClientCredentials. Then click Uložit.
  3. Copy the new app's Client Id from the list. That value is your Application ID.

[!IMPORTANT] The app must use the ClientCredentials flow. With an AuthorizationCode app, iDoklad rejects the login with Invalid parameter application_id.

2. Add the server to your AI client

Replace the ... placeholders with your three values.

Claude Code
bash
claude mcp add idoklad \  -e IDOKLAD_CLIENT_ID=... \  -e IDOKLAD_CLIENT_SECRET=... \  -e IDOKLAD_APPLICATION_ID=... \  -- npx -y idoklad-mcp
Claude Desktop (one-click install)
  1. Download the latest idoklad-mcp-<version>.mcpb from Releases.
  2. Double-click the file, or drag it into Claude Desktop → Settings → Extensions.
  3. Click Install, then fill in your Client ID, Client Secret and Application ID.

The extension is read-only by default. You can switch that off in its settings.

Claude Desktop (manual config)

Open Settings → Developer → Edit Config and add:

json
{  "mcpServers": {    "idoklad": {      "command": "npx",      "args": ["-y", "idoklad-mcp"],      "env": {        "IDOKLAD_CLIENT_ID": "...",        "IDOKLAD_CLIENT_SECRET": "...",        "IDOKLAD_APPLICATION_ID": "..."      }    }  }}

Restart Claude Desktop afterwards.

Codex

Add to ~/.codex/config.toml:

toml
[mcp_servers.idoklad]command = "npx"args = ["-y", "idoklad-mcp"]
[mcp_servers.idoklad.env]IDOKLAD_CLIENT_ID = "..."IDOKLAD_CLIENT_SECRET = "..."IDOKLAD_APPLICATION_ID = "..."
Cursor, VS Code and other clients

Use the same command, args and env values as in the Claude Desktop example, in your client's MCP settings.

3. Try it

Ask your assistant "Which of my iDoklad invoices are unpaid?"

Configuration

VariableRequiredDefaultDescription
IDOKLAD_CLIENT_IDyesFrom iDoklad → Settings → API
IDOKLAD_CLIENT_SECRETyesFrom iDoklad → Settings → API
IDOKLAD_APPLICATION_IDyesThe Client Id of your ClientCredentials app on developer.idoklad.cz
IDOKLAD_READ_ONLYnotrueSet to false to enable tools that create or change data
IDOKLAD_DOWNLOAD_DIRno~/DownloadsFolder where downloaded PDFs are saved

To use several companies, add the server once per company under different names (for example idoklad-firma-a and idoklad-firma-b), each with that company's credentials.

Read-only by default

Out of the box, the server can only read your data. To let the assistant create or change documents, set:

IDOKLAD_READ_ONLY=false

Write tools are marked as such, so clients can ask you to confirm before running them.

Tools

Documents: issued invoices, proforma invoices, credit notes, received invoices.

ToolModeWhat it does
list_issued_invoicesreadList issued invoices (vydané faktury), newest first. Filter by unpaid, paid, partly paid or overdue, customer, issue date or number.
list_proforma_invoicesreadSame for proforma invoices (zálohové faktury).
list_credit_notesreadSame for credit notes (dobropisy).
list_received_invoicesreadSame for received invoices (přijaté faktury), filtered by supplier.
get_issued_invoice, get_proforma_invoice, get_credit_note, get_received_invoicereadFull detail of one document: items, partner and totals.
get_document_pdfreadSave a document's PDF to your Downloads folder, optionally in another language or with payments.
create_issued_invoicewriteCreate an invoice from your default settings, or copy a previous invoice's settings. Supports currency (exchange rate filled in automatically), language, VAT rate and due date.
create_proforma_invoicewriteSame for proforma invoices (zálohové faktury).
create_invoice_from_proformawriteCreate the final invoice from a paid proforma (vyúčtování zálohy).
create_credit_notewriteCredit a whole invoice or selected items, with a reason. It can also settle the credit note against the invoice.
mark_document_paidwriteRecord full payment of an invoice, proforma or received invoice.
mark_document_unpaidwriteRemove payments, so the document is unpaid again.
send_document_emailwriteEmail an invoice, proforma or credit note through iDoklad, using your iDoklad email template.
send_payment_reminderwriteEmail an overdue payment reminder (upomínka) using your iDoklad reminder template.
send_payment_confirmationwriteEmail a customer a confirmation that their payment arrived.

Business overview

ToolModeWhat it does
get_business_statsreadIncome and costs by month, quarter or year, this year against last year, overdue amounts by age, VAT for the period, progress toward the VAT registration limit, and document counts.
get_top_partnersreadBiggest customers, or biggest debtors.
get_contact_statsreadHow a customer pays: invoices, paid, unpaid and late.

Contacts and price list

ToolModeWhat it does
list_contactsreadSearch contacts by name, IČO, DIČ or email.
get_contactreadFull detail of one contact.
create_contactwriteCreate a customer or supplier.
list_price_list_itemsreadSearch the price list (ceník) by name or code.

Everything else

ToolModeWhat it does
get_codebookreadCurrencies, countries, VAT rates, payment options, your bank accounts, numeric sequences and other lists.
search_api_docsreadSearch the full iDoklad API reference, which is bundled with the server.
idoklad_api_requestread / writeCall any iDoklad endpoint directly, e.g. bank statements, recurring invoices or stock. In read-only mode it only allows GET.

Privacy and security

  • The server runs on your computer. Your credentials stay in your local client configuration and are only sent to iDoklad.
  • Data the assistant reads from iDoklad, such as invoices and contacts, is passed to the AI model you use, just like anything else you share in the chat.
  • Treat your Client Secret like a password. Never commit it or paste it into a chat. To revoke it, delete it in iDoklad → Settings → API.

Troubleshooting

MessageFix
Missing environment variables: …One of the three credentials is not set in your client configuration.
Invalid parameter application_idYour developer portal app doesn't use the ClientCredentials flow, or you copied the wrong value. Use the app's Client Id.
iDoklad login failed (HTTP 400)Check the Client ID and Secret in iDoklad → Settings → API. They may have been regenerated.
HTTP 402Your iDoklad plan doesn't include the API, or your subscription has expired.
HTTP 429You've hit iDoklad's rate limit: 200 requests per minute, and a monthly quota that depends on your plan. The server retries on its own; wait and try again.

Roadmap

  • Issued invoices: list, detail, create
  • Currency for new invoices, and copying a previous invoice
  • Proforma invoices, credit notes, received invoices
  • Contacts and price list items
  • Payments (mark as paid or unpaid)
  • PDF download and sending documents by email
  • Generic tools: call any iDoklad endpoint, search the API docs
  • Create proforma invoices and credit notes, and invoices from paid proformas
  • Business overview: revenue, debtors, VAT, VAT registration limit
  • Payment reminders and payment confirmations
  • Partial payments
  • Supplier invoices from a PDF (iDoklad inbox)
  • Bank matching, editing and deleting documents, recurring invoices
  • One-click install for Claude Desktop, and a listing in the MCP Registry
  • Hosted version with iDoklad login (OAuth) for claude.ai and ChatGPT

Ideas and requests are welcome in issues.

Development

bash
git clone https://github.com/honzsik/idoklad-mcp.gitcd idoklad-mcpnpm installcp .env.example .env   # add your credentials
CommandWhat it does
npm testUnit tests against a fake API, with no network calls
npm run test:liveRead-only checks against your real iDoklad account (uses .env)
npm run smokeCalls the read tools through a real MCP connection
npm run evalsChecks that Claude picks the right tools for 30 Czech and English requests (see below)
npm run inspectOpens the tools in MCP Inspector
npm run buildCompiles to dist/
npm run build:api-indexRefreshes the bundled API reference from iDoklad's docs
npm run build:mcpbBuilds the Claude Desktop extension (idoklad-mcp-<version>.mcpb)

Evals

evals/ checks whether Claude picks the right tool, with the right inputs, for real requests such as "Které faktury jsou po splatnosti?" or "Invoice Globex like last time, but for 42 hours". Each case runs as a short conversation against a made-up iDoklad company, so no real data is touched. It also checks that Claude doesn't send emails or change documents unless asked.

bash
npm run evals                                  # all casesnpm run evals -- --only overdue-cs,mark-paid-csnpm run evals -- --repeat 3                    # models vary; run each case 3 times

It needs ANTHROPIC_API_KEY in .env from an account at console.anthropic.com with prepaid API credit. A Claude subscription doesn't include API credit. Each full run costs roughly $1–2. Run it after changing tool names, descriptions or inputs.

If you open this folder in Claude Code, it picks up .mcp.json and runs the server from source as idoklad-dev.

[!TIP] For anything that writes data, use a separate test company in iDoklad, so test invoices don't use up your real invoice numbers.

The code is in src/:

  • client.ts: the iDoklad API client. It handles login, token renewal and retries.
  • filter.ts: the iDoklad filter syntax.
  • tools/: the MCP tools.

Pull requests are welcome. Please run npm run typecheck && npm test before opening one.

Releasing

Pushing a version tag runs release.yml. It publishes to npm, creates a GitHub release with the Claude Desktop extension attached, and publishes to the MCP Registry:

bash
npm version minor        # or patch / major: updates package.json and creates a taggit push --follow-tags

Before tagging, move the changes in CHANGELOG.md under the new version.

License

MIT © Jan Vítek

Česky

idoklad-mcp je neoficiální MCP server pro iDoklad. Umožní AI asistentům (Claude, Codex, Cursor a dalším) číst a vystavovat faktury ve vašem iDokladu. Projekt není spojen se společností Seyfor, a. s.

Co budete potřebovat

  • Tarif iDokladu s přístupem k API: Oblíbený nebo Prémiový. Tarify Zdarma a Základní API nemají.
  • Node.js ve verzi 22 nebo novější.

Postup

  1. V iDokladu otevřete Nastavení → API a zkopírujte Client ID a Client Secret.
  2. Na developer.idoklad.cz si založte účet a vytvořte novou aplikaci s Flow: ClientCredentials. Její Client Id použijete jako IDOKLAD_APPLICATION_ID.
  3. Server přidejte do svého AI klienta podle návodu výše.
  4. Zeptejte se asistenta: „Které faktury v iDokladu jsou po splatnosti?"

Ve výchozím stavu server data jen čte. Vystavování faktur zapnete proměnnou IDOKLAD_READ_ONLY=false.

Pokud iDoklad hlásí Invalid parameter application_id, vytvořili jste aplikaci s jiným flow než ClientCredentials.

Source: README.md at commit a5e3998

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.4.0LatestNov 11, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Doklad integrations

Doklad.ai

ai.dokladOfficial publisher

Hosted Doklad.ai MCP server that lets an assistant create and send Czech invoices, manage customers and expenses, and summarise cash flow in your account.

Streamable HTTPWeb executableAuth
FinanceCredential requiredOct 28, 2026