idoklad-mcp

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.

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."

Related MCP server: SuperFaktura MCP Server

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.

2. Add the server to your AI client

Replace the ... placeholders with your three values.

claude mcp add idoklad \
  -e IDOKLAD_CLIENT_ID=... \
  -e IDOKLAD_CLIENT_SECRET=... \
  -e IDOKLAD_APPLICATION_ID=... \
  -- npx -y idoklad-mcp

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.

Open Settings → Developer → Edit Config and add:

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

Restart Claude Desktop afterwards.

Add to ~/.codex/config.toml:

[mcp_servers.idoklad]
command = "npx"
args = ["-y", "idoklad-mcp"]

[mcp_servers.idoklad.env]
IDOKLAD_CLIENT_ID = "..."
IDOKLAD_CLIENT_SECRET = "..."
IDOKLAD_APPLICATION_ID = "..."

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

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.

Business overview

Contacts and price list

Everything else

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

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

git clone https://github.com/honzsik/idoklad-mcp.git
cd idoklad-mcp
npm install
cp .env.example .env   # add your credentials

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.

npm run evals                                  # all cases
npm run evals -- --only overdue-cs,mark-paid-cs
npm 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.

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:

npm version minor        # or patch / major: updates package.json and creates a tag
git 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.