iDoklad

idoklad-mcp

チェコおよびスロバキアのオンライン請求書サービスであるiDoklad向けの非公式なMCPサーバーです。 Claude、Codex、Cursor、その他のAIアシスタントから、iDokladアカウントの請求書を閲覧・作成できます。

メモ

このプロジェクトはiDokladまたはSeyfor, a. s.と提携しておらず、承認も受けていません。 🇨🇿 チェコ語のガイド

警告

**開発初期段階（v0.4）です。**ツールや入力内容は今後変更される可能性があります。ロードマップをご覧ください。

質問できること

• 「期限を過ぎた請求書はどれですか？」
• 「ACMEは今年、いくら支払ってくれましたか？」
• 「Globex宛ての最新の請求書のPDFをダウンロードして。」
• 「受け取った請求書のうち、まだ支払っていないものはどれですか？」
• 「誰が一番多く未払いですか？」 / 「今年の業績は昨年と比べてどうですか？」
• 「VAT登録の義務が生じるまで、あといくらですか？」
• 「ACME s.r.o.宛てに、コンサルティング10時間分を1,500 CZK、支払期限を14日後として請求書を作成して。」（書き込みモードが必要です）
• 「先月と同じ内容でGlobex宛ての請求書を作成して。ただし42時間分にして。」（前回の請求書から通貨、VAT、言語を引き継ぎます）
• 「請求書20260018を今日付けで支払済みにして。」
• 「期限を過ぎたすべての請求書について、支払いリマインダーを送って。」
• 「請求書20260015のクレジットノートを発行して。クライアントが10ライセンス中2ライセンスを返品しました。」

要件

• APIアクセスを含むiDokladプラン：Oblíbený（Popular）またはPrémiový（Premium）。FreeおよびBasicプランにはAPIがありません。
• Node.js 22以降。
• MCPクライアント：Claude Desktop、Claude Code、Codex、Cursor、VS Codeなど。

セットアップ

1. 認証情報を取得する

3つの値が必要です。取得には5分ほどかかります。

Client IDとClient Secret（iDokladから取得）：

1. app.idoklad.czにサインインします。
2. Nastavení（設定）→ APIに移動します。
3. Client IDとClient Secretをコピーします。

これらは、1つの会社（事業所）と1人のユーザーにひも付いています。

Application ID（iDoklad開発者ポータルから取得）：

1. developer.idoklad.czでアカウントを作成します。
2. Nová aplikaceで任意の名前を入力し、FlowをClientCredentialsに設定します。その後、Uložitをクリックします。
3. 一覧に表示された新しいアプリのClient Idをコピーします。この値がApplication IDです。

重要

アプリではClientCredentialsフローを使用する必要があります。AuthorizationCodeアプリでは、iDokladがInvalid parameter application_idというエラーを返し、ログインできません。

2. AIクライアントにサーバーを追加する

...のプレースホルダーを3つの値に置き換えてください。

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 ドキュメントの検索
• プロフォーマ請求書とクレジットノートの作成、および支払済みプロフォーマ請求書からの請求書作成
• 事業概要：収益、債務者、VAT、VAT 登録の上限
• 支払いリマインダーと支払い確認
• 一部支払い
• PDF からの仕入先請求書（iDoklad インボックス）
• 銀行照合、書類の編集と削除、定期請求書
• Claude Desktop のワンクリックインストールと MCP Registry への掲載
• claude.ai と ChatGPT 向けの iDoklad ログイン（OAuth）対応ホスト版

アイデアやご要望は issues でお寄せください。

開発

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

評価テスト

evals/ では、「Které faktury jsou po splatnosti?」 や 「Invoice Globex like last time, but for 42 hours」 といった実際のリクエストに対して、Claude が適切なツールを適切な入力で選ぶかを確認します。各ケースは架空の 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

実行には、console.anthropic.com のアカウントでプリペイド API クレジットを用意し、.env に ANTHROPIC_API_KEY を設定する必要があります。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. とは関係ありません。

必要なもの

• API にアクセスできる iDoklad プラン：Oblíbený または Prémiový。Zdarma と Základní の各プランには API がありません。
• バージョン 22 以降の Node.js。

手順

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 を設定します。

iDoklad から Invalid parameter application_id と表示された場合、ClientCredentials 以外のフローを使用してアプリケーションを作成しています。