informer-mcp

Model Context Protocol サーバーで、Informer の簿記API (v2) に対応しています。あらゆるMCPクライアントから、取引先、売上請求書と仕入請求書、見積書、注文書、領収書、製品、財務レポートに直接アクセスできます。

すべてのツールは、Informer 自身の OpenAPI ドキュメント（api.informer.eu/docs/v2）に基づいています。サーバーにはそのコピーが同梱されているためオフラインでも動作し、常に最新の状態に保たれます — APIの変更への追従 を参照してください。

非公式プロジェクトです。Informer とは提携しておらず、Informer による推奨も受けていません。

クイックスタート

MCPサーバーをインストールできるAIアシスタントに、これを貼り付けてください:

Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

リポジトリをクローンし、ビルドし、サーバーをクライアントに登録したうえで、informer-mcp setup を実行します。すると 127.0.0.1 のブラウザにページが開きます。そのページにAPI認証情報を入力します。チャットで何かを尋ねられることはなく、キーが会話に貼り付けられることもありません。

そのページに表示されるもの

管理ごとに1枚のカードが表示され、複数の管理を担当している場合は管理を追加も表示されます:

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

どちらの認証情報も1つの管理に属しているため、簿記担当者はクライアントごとに1枚のカードを追加します。複数のクライアント管理 を参照してください。

「Verify & save」を押すとどうなるか

1. 各キー/セキュリティコードのペアがAPIに対して検証され、そのペアが実際に属する会社名がページに表示されます。そのため、間違った行に貼り付けたキーは、何かを保存する前に明らかになります。

2. ペアが拒否された場合、何も書き込まれず、失敗した行が示されます。オフラインのときなど、それでも保存したい場合は 検証せずに保存 にチェックを入れます。

3. 成功すると、認証情報はパーミッション 0600 で ~/.informer-mcp.json に書き込まれます。open_setup から開いた場合、実行中のサーバーは変更を即座に反映し、次のメッセージで新しい管理を選択できるようになります。ターミナルから開いた場合は、クライアントを再起動してください。

確認するには 「どの管理にアクセスできますか？」 と尋ねてください。list_administrations が呼び出され、各エイリアスとその会社が一覧表示されます。

Related MCP server: billingo-mcp

得られるもの

• 68のツール — 文書化された全49エンドポイントをカバー。読み取りおよび書き込み。

• ブラウザでのセットアップ。 アシスタントにセットアップページを開くよう依頼するか、informer-mcp setup を実行します。すべてのキーをAPIに対して検証し、設定ファイルを書き込み、再起動なしで変更が反映されます。

• APIに追随。 Informer が新しいエンドポイントを公開すると、クライアントが接続されたままサーバーがそれを検出してツールを追加します — 再インストールも再起動も不要です。

• 1つのサーバーに複数のクライアント管理。 簿記担当者は1つの接続からすべてのクライアントの帳簿にアクセスできます。複数が設定されている場合、administration 引数は必須です。

• ポートフォリオ全体への1つの質問。 読み取り専用ツールはエイリアスのリストまたは "all" を受け付け、それらを並行してクエリし、クライアントごとにキー付けされた結果を返します。

• 完全なリクエストスキーマ。 作成/更新ツールはペイロードの完全なJSON Schemaを公開するため、モデルは何かを送信する前に、どのフィールドが存在し、どれが必須かを把握できます。

• 読み取り専用か読み書きか、お好みで。 --read-only フラグは何かを変更するすべてのツールを非表示にし、個々のクライアントを読み取り専用に固定することも、残りは書き込み可能なままにすることもできます。許可/拒否リストでさらに範囲を絞り込めます。

• PDFと添付ファイル はbase64からデコードされ、そのままディスクに書き込めます。

• 堅牢なHTTP。 タイムアウト、Retry-After 対応のリトライ、Informer のオランダ語の検証エラーをそのまま表示します（HTTP 422: invoice_date: ongeldig）。

要件

• Node.js 20 以降

• APIアクセス権のある InformerOnline アカウント

認証情報の設定

会話の中で、こう尋ねるだけです:

「Informer の管理を変更したい」 「Informer に新しいクライアントを追加したい」 「Informer のAPIキーが変わった」

アシスタントが open_setup ツールを呼び出すと、ページが開きます。探すべき設定ファイルも、手で編集するものもありません。ページはブラウザ上のフォームなので、APIキーをチャットに入力する必要もありません。

同じページをターミナルから開く場合:

npm run setup          # or: informer-mcp setup

どちらの方法でも、ブラウザに http://127.0.0.1:<port> が表示され、管理ごとにフォームが用意されています。エイリアス、会社名、APIキー、セキュリティコード、書き込み可能かどうかです。保存時には各ペアがAPIに対して検証されるため、入力ミスのキーはすぐに検出され、各キーが実際に属する会社名が表示されます。その後、パーミッション 0600 で ~/.informer-mcp.json に書き込まれます。

認証情報をまったく設定せずにサーバーを起動すると、まさにそのタイミングで必要になるため、同じページが自動的に開きます。オフにするには INFORMER_AUTO_SETUP=false を設定します。ヘッドレスマシンでは INFORMER_OPEN_BROWSER=false を設定するとURLだけが表示されます。どのように開いた場合でも、ページは常に1つだけで、再度要求しても同じURLが返されます。

このページが意図的に行う点をいくつか挙げます:

• 127.0.0.1 にのみバインドし、実行のたびにランダムなトークンを生成して、URLと保存リクエストの両方に含めるようにします。そのため、ブラウザ内の別のサイトからアクセスして保存することはできません。

• 保存済みのキーをページに送り返すことはありません。既存の管理は認証情報を空欄にして表示され、新しい値を入力しない限り保持されます。

• APIが拒否した認証情報は保存しません。ただし、検証せずに保存 にチェックを入れた場合は除きます。

ファイルや環境変数を手で書くことを妨げるものはありません。ページは便利なだけで、必須ではありません。

キーの入手先

APIは2つのヘッダーで認証します。どちらも必須です:

どちらも1つの管理に限定されています。APIキーは、それが作成された管理に属し（GET /administration は「このAPIキーにリンクされた管理」を返します）、セキュリティコードはその会社を識別します。管理を一覧表示したり、管理を切り替えたりするエンドポイントはありません。

キーは、その管理の帳簿への完全なアクセスを許可します。パスワードと同じように扱ってください。環境変数、シークレットマネージャー、またはリポジトリ外の設定ファイルに保存してください。

複数のクライアント管理

複数のクライアントを抱える簿記担当者は、クライアント管理ごとに1組のキー/セキュリティコードが必要です。管理にアクセスできる会計士ユーザーは、その設定から作成できます。セットアップページで追加するか、~/.informer-mcp.json（または INFORMER_CONFIG_FILE で指定した任意のファイル）を自分で書いてください:

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

複数の管理が設定されている場合、すべてのツールで administration 引数が必須となり、エイリアスのenumとして提示されます:

list_sales_invoices({ "administration": "acme", "filter": "open" })

意図的にデフォルトはありません。請求書を誤ったクライアントの元帳に計上することは、静かに起きてはいけない唯一のミスです。そのため、引数なしの呼び出しは、HTTPリクエストが行われる前にスキーマ検証で拒否されます。設定していないエイリアスも同様です。

list_administrations は設定済みのエイリアスを表示します。verify: true を渡すと、各会社名をAPIから取得し、認証情報が機能することと、すべてのエイリアスが意図した会社を指していることの両方を確認できます。

複数のクライアントを一度にクエリする

読み取り専用ツールはエイリアスのリストまたは "all" も受け付けます:

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

管理は並行してクエリされ（INFORMER_FANOUT_CONCURRENCY、デフォルトでは同時に4つ）、結果はエイリアスでキー付けされます:

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

知っておきたい3つの特性:

• 1つのクライアントが失敗してもクエリ全体は失敗しません。 そのエントリには error が含まれ、残りは引き続きデータを返します。

• レスポンスの割り当ては均等に分割されます。 各管理には INFORMER_MAX_RESPONSE_CHARS / n 文字が割り当てられるため、1つの大きなクライアントが他のクライアントを締め出すことはありません。割り当てを超えた分は { "truncated": true, "partial": ... } として返されます。

• ファンアウトは読み取り専用です。 書き込みを行うツールとPDF/添付ファイルのダウンロードは単一のエイリアスを受け取ります。それらのスキーマには配列や "all" すら用意されておらず、ハンドラーもそれらを拒否します。12の管理に同じ請求書を作成してしまう事故を可能にする価値はありません。

管理が1つの場合は、従来どおりAPIペイロードがラップされずにそのまま返されます。

管理が1つの場合（一般的なケース）は何も変わりません。通常どおり INFORMER_API_KEY と INFORMER_SECURITY_CODE を設定すれば、引数は省略可能なままです。

インストール

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

セットアップページは 127.0.0.1 で実行され、すべてのキーをAPIに対して検証し、~/.informer-mcp.json に書き込みます。認証情報の設定 を参照してください。

Claude Desktop の拡張機能として

最も簡単な方法: バンドルをビルドして開きます。

npm run bundle          # writes informer-mcp.mcpb

Claude Desktop で 設定 → 拡張機能 → 詳細設定 → 拡張機能をインストール… に移動し、.mcpb ファイルを選択します。このファイルは依存関係を内包しているため、Node.js 20 以外に事前にインストールするものはありません。

インストールダイアログでは、APIキー、セキュリティコード、読み取り専用スイッチが提供されます。3つすべて空のままにできます: その場合、サーバーは初回起動時にセットアップページを開きます。これは複数の管理を設定する唯一の方法でもあります。

Claude Desktop の 設定 → コネクタ → カスタムコネクタを追加 は別物です。リモートMCPサーバーのURLを受け取ります。このサーバーはstdio上でローカルに実行されるため、コネクタではなく拡張機能としてインストールされます。

Claude Desktop を手動で設定する

設定ファイルを直接編集します:

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

その後、Claude Desktop を再起動してください。Windows では、JSON内のバックスラッシュは2重にする必要があります。フォワードスラッシュも使え、読みやすくなります。

その他のMCPクライアント

サーバーはstdio上でMCPを話すため、どのクライアントでも同じ方法（コマンドとその引数）で設定します。上記のブロックは、Claude Code（claude mcp add）、Cursor、Zed、その他MCPを話すあらゆる環境でそのまま動作します。

認証情報は ~/.informer-mcp.json から読み込まれるため、クライアント設定で繰り返す必要はありません。クライアントごとに渡す場合は、INFORMER_API_KEY と INFORMER_SECURITY_CODE を含む env ブロックを追加するか、INFORMER_CONFIG_FILE を別の場所に指定してください。

"--read-only" を args に追加すると、何も変更できないサーバーを登録できます（読み取り専用か読み書き可能か を参照）。同じサーバーを2つの名前で登録し、一方を読み取り専用、もう一方を読み書き可能にすることも有効です。

stdout はプロトコルを運ぶため、ログはすべて stderr に出力されます。起動時の1行のバナーに、登録されたツールの数と検出された事業所が表示されます。

読み取り専用か読み書き可能か

デフォルトではすべてのツールが利用可能です。書き込みツールを完全に無効にするには、フラグを付けてサーバーを起動します:

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

INFORMER_READ_ONLY=true でも同じ動作になります。フラグは環境変数より優先されます。つまり、1つのクライアントに同じサーバーを2回登録し、1つは日常的な質問用の読み取り専用、もう1つは実際に予約を行うセッション用の読み書き可能として使い分けることができます。

読み取り専用モードでは、書き込みツールは一切登録されません。ツール一覧に表示されることがないため、モデルが書き込みツールを呼び出すことはできません。

クライアントごとの設定

個々の事業所は設定ファイルで固定できます。これは、一部のクライアントの帳簿しか参照しない場合に便利です:

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

"read_only": true は短縮形として機能します。最も制限の厳しい設定が優先されます:

つまり、読み取り専用とマークされたクライアントに誤って書き込まれることはなく、--read-only で開始されたセッションは、設定ファイルの内容に関係なく読み取り専用のままです。

一部の事業所が書き込み可能で他がそうでない場合、書き込みツールは登録されたままですが、その administration 列挙型には書き込み可能なものだけが含まれます。読み取り専用クライアントでの請求書作成リクエストは、HTTP リクエストの前に拒否されます:

Administration(s) bakkerij are configured as read-only, so this tool cannot change them.
Writable: acme, garage.

list_administrations は各クライアントの有効なモードを報告し、起動バナーに要約が表示されます: read-write: acme, garage。

設定

フィルタは OpenAPI タグまたはツール名を受け付け、大文字小文字と句読点を無視して照合されます:

# read-only access to invoicing data
INFORMER_TOOLS="Sales Invoices,Relations" node dist/index.js --read-only

# everything except deleting attachments
INFORMER_EXCLUDE_TOOLS=delete_sales_invoice_attachment node dist/index.js

使い方

接続したら、自然言語で質問します:

• 「2026年の売上請求書で未払いのものはどれ？」 → filter を指定した list_sales_invoices

• 「ACME に €125 のコンサルティング10時間分の下書き請求書を作成して」 → 有効な元帳/VAT/テンプレート ID を取得する get_sales_invoice_options、次に create_sales_invoice

• 「請求書12345を PDF としてデスクトップにダウンロードして」 → save_path を指定した get_sales_invoice_pdf

• 「2026年の第6期の貸借対照表を表示して」 → get_balance_report

知っておくべき規約

• 事業所を明示的に選択してください。 複数のクライアントが設定されている場合、すべてのツールは administration: "<alias>" を受け取ります。list_administrations はエイリアスを会社にマッピングし、読み取り専用ツールはリストまたは "all" も受け入れます。

• 日付 は常に YYYY-MM-DD です。

• 一覧ツールはページネーション に対応しており、page（デフォルト1）と records（デフォルト20）を使用し、total と pages を含む pagination オブジェクトを返します。

• リクエストペイロードは単一の body 引数に格納します。 パスパラメータとクエリパラメータはトップレベルに残るため、update_relation は { "id": 42, "body": { ... } } を受け取ります。

• ドキュメントを作成するときは、最初に *_options ツールを呼び出してください。 get_sales_invoice_options、get_quotation_options などは、事業所の有効な元帳、VAT、テンプレート、通貨、支払条件の ID を返します。

• レポートには明示的な範囲が必要です。 get_balance_report には year_from、year_to、period が必要です。get_column_balance_report には元帳の範囲も必要です。

PDF と添付ファイル

Informer はファイルを JSON 内の base64 として返します。これを行うツール（get_*_pdf、download_sales_invoice_attachment）は、オプションの save_path を受け取ります:

• save_path あり — ファイルはデコードされてそのパスに書き込まれ、ツールは { saved_to, filename, bytes, mime_type } を返します。

• save_path なし — ファイルは適切な MIME タイプのインライン MCP リソースとして返されます。大きなドキュメントの場合、コンテキスト上でコストが高くなる可能性があります。

アップロードは逆の方法で機能します: upload_sales_invoice_attachment は { filename, file } を受け取ります。file は base64 エンコードされたコンテンツです（最大10 MB。PDF、PNG、JPEG、GIF、DOC(X)、XLS(X) に対応）。

ツールリファレンス

npm run tools は現在の仕様からこのリストを出力します。npm run tools -- --md は以下の表を再生成します。

エンドポイントツールの他に、サーバー提供のツールが3つあります:

管理

取引先

連絡先

売上請求書

仕入請求書

定期請求書

販売注文

見積書

売上帳

支払条件

テンプレート

VAT

元帳

コスト

通貨

仕訳帳

サブスクリプションタイプ

添付ファイル

製品

領収書

メモランダム

レポート

ツールの命名

名前は説明文ではなくHTTPメソッドとパスから派生するため、仕様の更新後も安定しています。

命名テーブルが認識しないエンドポイントは <動詞>_<パススラッグ> にフォールバックするため、仕様の更新でツールが壊れることはありません。

APIの変更への追従

ツールはInformerのOpenAPIドキュメントから生成されるため、Informerがエンドポイントを追加した場合、必要なのはそのドキュメントの新しいコピーだけです。サーバーはそれを自分で取得できます。

優先順位の高い順に3つのレイヤーがあります。

1. ダウンロードしたコピー：~/.informer-mcp.spec.json にキャッシュされます。

2. バンドルされたコピー：openapi/api-docs.json にあり、サーバーに同梱され、常にオフラインで動作します。

3. どちらも盲目的に信頼されることはありません。ダウンロードは、少なくとも1つの使用可能な操作を持つOpenAPI 3ドキュメントとして解析できなければ拒否され、現在のツールが維持されます。キャプティブポータルやメンテナンスページでツールセットが消去されることはありません。

スケジュールに基づく更新

サーバーは起動後すぐに、1日に1回、バックグラウンドで新しいドキュメントをチェックします。起動がブロックされることはなく、失敗したチェックはログに記録されて無視されます。INFORMER_SPEC_MAX_AGE_HOURS=0 で無効にできます。

オンデマンド更新

refresh_api_spec ツールは、要求したときに同じことを行います。期待するエンドポイントが見つからない場合や、引数が不明として拒否された場合に便利です。

「InformerのAPI説明を更新して、何が変わったか教えてください。」

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

dry_run を渡すと、何も適用せずにそのレポートを確認できます。

差分は意図的に具体的です。追加されたツールと削除されたツールを名前で示し、変更されたツールについては 何が 変わったか（新しい引数、削除された引数、必須になったフィールド）を示します。これは単純なパス比較では見逃される部分であり、通常は不可解な 422 として表面化する部分です。

ドキュメントを採用すると、実行中のサーバーが更新されます。新しいツールが登録され、撤回されたツールは削除され、変更されたツールは再公開され、tools/list_changed 通知が送信されるため、クライアントはセッション中にリストを再読み込みします。

リポジトリ内のコピー

npm run update-spec は バンドルされた ドキュメントを更新し、どのパスが追加・削除されたかを報告します。これは、サーバーをインストールするすべての人に変更をコミットしたい場合に実行するものです。refresh_api_spec は自分のマシンにのみ影響します。

リソース

サーバーはOpenAPIドキュメント自体をMCPリソースとして informer://openapi.json で公開します。これは、モデルにフィールド定義を推測させずに確認させたい場合に便利です。

開発

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

プロジェクト構成

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb

通常、エンドポイントの追加はコード変更を伴いません。実行中のサーバーが自動的に取得し、npm run update-spec で同じ変更をバンドルされたコピーにコミットします。本当に新しいURL形状の場合のみ、src/openapi.ts の RESOURCES テーブルにルールを追加する必要があります。ルールがなくてもツールにはなりますが、名前が少し平凡になります。

スキーマの変換方法

OpenAPI 3.0はJSON Schemaと完全には一致しません。MCPツール定義に変換する過程で：

• #/components/schemas/X 参照は #/$defs/X になり、各操作が実際に必要とする推移的クロージャのみがインライン化されるため、ツール定義は小さく保たれます。

• nullable: true は ["type", "null"] のユニオンになります。

• パスパラメータとクエリパラメータはトップレベルのプロパティになり、リクエストボディは body の下に置かれ、additionalProperties: false によってタイプミスがAPIに到達するのを防ぎます。

引数は、HTTP呼び出しが行われる前にそのスキーマに対して検証されます。

安全上の注意

• このサーバーは、実際の簿記記録を作成、更新、削除できます。レポートのみが必要な場合は --read-only で開始し、個々のクライアントを "mode": "read-only" で固定し、書き込みツールの承認をMCPクライアントに求めるようにします。

• 1つのプロセスに複数クライアントの認証情報があると、ルーティングを誤った呼び出しが他人の台帳に触れることになります。必須の administration 引数、既知のエイリアスのenum、ファンアウトの読み取り専用制限、およびすべてのエラーメッセージのエイリアスプレフィックス（[acme] HTTP 422: ...）は、すべてそのためです。設定ファイルはバージョン管理の対象外にし、自分だけが読み取れるようにしてください。

• ツールには readOnlyHint、destructiveHint、idempotentHint の注釈が付けられているため、これらのヒントを使用するクライアントは危険なツールを制限できます。

• stdout には何もログ出力されず、認証情報がツール出力にエコーされたり、セットアップページに送り返されたりすることはありません。open_setup はURLを返しますが、キーは返しません。アシスタントがあなたの認証情報を読み取る方法はなく、チャットでそれらを尋ねる理由もありません。

• APIの説明は認証情報なしでダウンロードされ、利用可能なOpenAPI 3ファイルとして解析できないドキュメントは採用されずに拒否されます。

ライセンス

MIT — LICENSE を参照してください。