iDoklad

idoklad-mcp

适用于 iDoklad 的非官方 MCP 服务。iDoklad 是面向捷克和斯洛伐克的在线发票服务。 它支持 Claude、Codex、Cursor 和其他 AI 助手读取并创建 iDoklad 账户中的发票。

说明

本项目与 iDoklad 或 Seyfor, a. s. 无关联，也未获其认可。 🇨🇿 捷克语指南

警告

早期开发阶段（v0.4）。 工具及其输入仍可能发生变化。请参阅路线图。

你可以询问什么

• “哪些发票已逾期？”
• “ACME 今年付给我们多少钱？”
• “下载 Globex 最近一张发票的 PDF。”
• “哪些收到的发票我们还没付款？”
• “谁欠我最多？” / “今年的业绩比去年如何？”
• “距离必须注册增值税还差多少？”
• “为 ACME s.r.o. 创建一张发票：咨询 10 小时，每小时 1,500 CZK，14 天后到期。”（需要写入模式）
• “像上个月那样给 Globex 开发票，但改成 42 小时。”（从上一张发票复制币种、增值税和语言）
• “将发票 20260018 标记为今天已付款。”
• “为所有逾期发票发送付款提醒。”
• “为发票 20260015 开具贷项通知单，客户退回了 10 个许可证中的 2 个。”

要求

• iDoklad 套餐必须包含 API 访问权限：Oblíbený（Popular）或 Prémiový（Premium）。Free 和 Basic 套餐不提供 API。
• Node.js 22 或更高版本。
• 一个 MCP 客户端：Claude Desktop、Claude Code、Codex、Cursor、VS Code 等。

设置

1. 获取凭据

你需要三个值。获取它们大约需要五分钟。

Client ID 和 Client Secret，从 iDoklad 获取：

1. 登录 app.idoklad.cz。
2. 前往 Nastavení（Settings）→ API。
3. 复制 Client ID 和 Client Secret。

这些凭据对应一家公司的账簿（agenda）和一位用户。

Application ID，从 iDoklad 开发者门户获取：

1. 在 developer.idoklad.cz 创建账户。
2. 在 Nová aplikace 下输入任意名称，并将 Flow 设为 ClientCredentials。然后点击 Uložit。
3. 从列表中复制新应用的 Client Id。该值就是你的 Application ID。

重要

应用必须使用 ClientCredentials flow。如果使用 AuthorizationCode 应用，iDoklad 会拒绝登录，并返回 Invalid parameter application_id。

2. 将服务添加到 AI 客户端

将 ... 占位符替换为你的三个值。

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

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

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

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

3. 试用

向助手询问 “我的 iDoklad 发票中，哪些尚未付款？”

配置

如需使用多家公司，请在不同名称下为每家公司各添加一次服务（例如 idoklad-firma-a 和 idoklad-firma-b），并分别使用对应公司的凭据。

默认只读

开箱即用时，该服务只能读取你的数据。若要允许助手创建或更改文档，请设置：

IDOKLAD_READ_ONLY=false

写入工具会明确标注，因此客户端可以在运行前请求你确认。

工具

单据：已开具发票、形式发票、贷项通知单、收到的发票。

业务概览

联系人和价目表

其他所有内容

隐私与安全

• 服务运行在你的计算机上。你的凭据保存在本地客户端配置中，仅会发送给 iDoklad。
• 助手从 iDoklad 读取的数据（例如发票和联系人）会传递给你使用的 AI 模型，就像你在聊天中分享的其他内容一样。
• 请像对待密码一样保护你的 Client Secret。切勿将其提交到代码库或粘贴到聊天中。如需撤销，请在 iDoklad → Settings → API 中将其删除。

故障排除

路线图

• 已开具发票：列表、详情、创建
• 新发票的货币，以及复制之前的发票
• 形式发票、贷项通知单、已收到的发票
• 联系人和价目表项目
• 付款（标记为已付款或未付款）
• 下载 PDF，以及通过电子邮件发送单据
• 通用工具：调用任意 iDoklad 端点、搜索 API 文档
• 创建形式发票和贷项通知单，以及根据已付款的形式发票创建发票
• 业务概览：收入、欠款方、增值税、增值税注册限额
• 付款提醒和付款确认
• 部分付款
• 根据 PDF 创建供应商发票（iDoklad 收件箱）
• 银行匹配、编辑和删除单据、定期发票
• Claude Desktop 一键安装，以及在 MCP Registry 中上架
• 支持通过 iDoklad 登录（OAuth）的托管版本，适用于 claude.ai 和 ChatGPT

欢迎在 问题 中提出想法和需求。

开发

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

评测

evals/ 用真实请求检查 Claude 是否能选择正确的工具并提供正确的输入，例如 “哪些发票已逾期？” 或 “像上次一样给 Globex 开具发票，但按 42 小时计算”。每个用例都会针对一家虚构的 iDoklad 公司进行简短对话，因此不会触及任何真实数据。它还会检查 Claude 是否会在未被要求时发送电子邮件或更改单据。

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

你需要在 .env 中设置 ANTHROPIC_API_KEY，并使用 console.anthropic.com 上拥有预付费 API 额度的账户。Claude 订阅不包含 API 额度。每次完整运行的费用约为 $1–2。更改工具名称、描述或输入后请运行评测。

如果你在 Claude Code 中打开此文件夹，它会读取 .mcp.json，并以 idoklad-dev 的名称从源代码运行服务。

提示

对于任何会写入数据的操作，请在 iDoklad 中使用单独的测试公司，以免测试发票占用真实发票编号。

代码位于 src/：

• client.ts：iDoklad API 客户端，负责登录、令牌续期和重试。
• filter.ts：iDoklad 筛选语法。
• tools/：MCP 工具。

欢迎提交拉取请求。提交前请运行 npm run typecheck && npm test。

发布

推送版本标签会运行 release.yml。它会发布到 npm，创建一个附带 Claude Desktop 扩展的 GitHub 发布，并发布到 MCP Registry：

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

创建标签前，请将 CHANGELOG.md 中的变更移到新版本下。

许可证

MIT © Jan Vítek

捷克语

idoklad-mcp 是适用于 iDoklad 的非官方 MCP 服务。它允许 AI 助手（Claude、Codex、Cursor 等）读取和开具 iDoklad 中的发票。本项目与 Seyfor, a. s. 无关联。

准备工作

• iDoklad 支持 API 访问的套餐：Oblíbený 或 Prémiový。Zdarma 和 Základní 套餐不支持 API。
• Node.js 22 或更高版本。

操作步骤

1. 在 iDoklad 中打开 设置 → API，并复制 Client ID 和 Client Secret。
2. 在 developer.idoklad.cz 注册账号，并创建一个 Flow: ClientCredentials 的新应用。将其 Client Id 用作 IDOKLAD_APPLICATION_ID。
3. 按照上方的说明将服务添加到 AI 客户端。
4. 询问助手：“iDoklad 中哪些发票已逾期？”

默认情况下，服务仅读取数据。将变量 IDOKLAD_READ_ONLY=false 设置为 false 即可启用开具发票功能。

如果 iDoklad 报告 Invalid parameter application_id，说明你创建的应用使用了 ClientCredentials 以外的流程。