Oblio

Oblio MCP サーバー

AI アシスタントから、Oblio の API を通じてルーマニア企業の請求書を発行・管理できます。クライアント、商品、シリーズ、VAT 税率、発行済み請求書を読み取り、請求書とプロフォーマを発行し、支払いを記録するほか、請求書のキャンセル、復元、取り消し、削除を行います。財務書類を作成、変更、または元に戻すすべてのツールは money です。クライアントはまず確認を求め、ANAF の確認方法に沿って計算した合計金額を表示します。

必要なもの：Oblio アカウント、API シークレット、そしてサーバーが処理する会社の納税者番号（CIF）です。サンドボックスはありません。ここで発行した請求書は実際のもので、シリーズの次の番号が割り当てられます。

できること

• 「9月分で未払いの請求書はどれですか？」
• 「Client SRL に、1時間あたり1,000 RON、21%のVATを加算したコンサルティング8時間分の請求書を発行してください。支払期限は30日後です。」
• 「Client SRL が本日、請求書 FCT 0042 の代金として1,000 EURを銀行振込で支払いました。記録してください。」
• 「プロフォーマ PRF 0007 を請求書に変換してください。」
• 「請求書 FCT 0042 を取り消し、記録済みの支払いはそのまま残してください。」

インストール

Claude Code の場合：

claude mcp add oblio -e OBLIO_CONFIG="<path to Oblio app.json>" -- npx -y @foreverworks/mcp-oblio

Claude Desktop（Settings、Developer、Edit Config）やその他の多くのクライアントでは、同じコマンドを JSON として読み込みます：

{
  "mcpServers": {
    "oblio": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-oblio"],
      "env": {
        "OBLIO_CONFIG": "<path to Oblio app.json>"
      }
    }
  }
}

いずれも Node 22.19 以降で公開済みパッケージを実行します。VS Code と Claude Desktop のバンドルでは、サーバーの追加時に OBLIO_CONFIG の入力を求められます。Cursor では代わりに環境変数（${env:OBLIO_CONFIG}）から読み込むため、Cursor の起動前に設定してください。設定では、この変数に指定する内容を説明しています。

クローンから実行

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add oblio -e OBLIO_CONFIG="<path to Oblio app.json>" -- node "$PWD/servers/oblio/dist/index.js"

JSON 設定では、コマンドは node、その引数は servers/oblio/dist/index.js のフルパスです。複数のクライアント間で実行中のコピーを HTTP 経由で共有する方法については、docs/deploying.md を参照してください。

設定

変数	必須	説明
OBLIO_CONFIG	はい	app.json（下記）のパスです。サーバーはこのファイルを読み取るだけです。systemd でこの変数が未設定の場合は、CREDENTIALS_DIRECTORY 内の app.json（LoadCredential=app.json:<path>）が使用されます。
OBLIO_STATE_DIR	いいえ	アクセストークンのキャッシュ保存先です。デフォルトの場所はdocs/configuration.mdに記載されています。

app.json には3つの値があり、すべて必須です：

{
  "client_id": "<the email you sign in to Oblio with>",
  "client_secret": "<the API secret>",
  "company_cif": "<the CIF of the company every call acts on>"
}

company_cif にデフォルト値はないため、会社名が指定されていない状態で処理を実行することはありません。 api_base と token_url は、テストやプロキシ用に Oblio のエンドポイントを上書きします。 サーバーが app.json に書き込むことはなく、エラーには値ではなく、不正なフィールド名が示されます。

API シークレットの取得

1. Oblio のウェブアプリにサインインします。
2. Settings、次に Account Data（Setari, Date cont）を開き、API シークレットをコピーします。
3. サインインに使用したメールアドレスを client_id として、app.json の client_secret にシークレットを設定します。

Oblio ではアカウントのパスワードをリセットするたびに新しいシークレットが生成されるため、リセット後は app.json のシークレットを新しいものに更新する必要があります。

状態フォルダーには access_token.json が保存されます。これは Oblio がシークレットに対して発行する有効期間 1 時間のトークンで、モード 0600 で書き込まれ、プロセス間でロックされます。すべてのサーバーが共有する変数（トランスポート、制限、確認）は、docs/configuration.md に記載されています。

初回実行

1. アシスタントに Oblio の health チェックを実行するよう依頼します。アカウント、app.json に設定された会社の CIF、アカウントがその会社にアクセスできるかどうかが返されます。拒否されたシークレットは、何かが発行される前にここで確認できます。
2. シリーズ（list_series）と VAT 税率（list_vat_rates）を確認します。請求書では、Oblio が指定する名前でシリーズと各明細の税率を指定するためです。

シェルから node dist/index.js --health を実行すると、OBLIO: で始まる行が 1 行表示され、認証情報が機能しない場合はゼロ以外の終了コードで終了します。タイマーによる実行に適しています。

ツール

read は何も変更しません。write は Oblio アカウントの何かを変更します。money は会計書類を作成、変更、または取り消すもので、クライアントは呼び出しごとに確認を求めます。

ツール	アクセス	説明
health	read	サーバーが稼働しているか、どのアカウントとして、どの会社の CIF にアクセスしているか、またアカウントがその CIF にアクセスできるかどうかを確認します。常に Oblio に問い合わせます。
list_companies	read	アカウントに紐づいている会社を一覧表示します。10 分間キャッシュされます。
list_clients	read	保存済みのクライアントを、名前または CIF で絞り込み、1 ページずつ表示します。キャッシュされません。
list_products	read	保存済みの商品とサービスを、名前またはコードで絞り込み、1 ページずつ表示します。キャッシュされません。
list_series	read	書類のシリーズと、各シリーズで次に発行される番号を表示します。10 分間キャッシュされ、発行または削除後にキャッシュが破棄されます。
list_vat_rates	read	明細の vat_name と vat_percentage に指定できる VAT 税率を表示します。10 分間キャッシュされます。
list_invoices	read	期間、シリーズ、購入者、ステータス（未払い、支払い済み、キャンセル済み）、e-Factura の状態で絞り込んだ発行済み請求書を、新しい順に 1 ページずつ表示します。
get_invoice / get_proforma	read	シリーズと番号を指定して書類を 1 件取得し、PDF と e-Factura のリンク、合計金額、支払いを表示します。
create_proforma	write	仮請求書を発行します。会計書類ではありませんが、シリーズ内の番号を使用します。
create_invoice	money	請求書を発行します。
invoice_from_proforma	money	仮請求書を参照する請求書を発行します。仮請求書のクライアント、明細、合計金額を引き継ぎます。
collect_invoice	money	発行済み請求書に対して受領した支払いを記録します。支払い方法、金額、日付、参照情報を指定します。
cancel_invoice / restore_invoice	money	請求書をキャンセルします（番号は使用済みのままです）。または、その操作を取り消します。
reverse_invoice	money	発行済み請求書の取消請求書（ストルノ）を発行します。合計金額は元の請求書と正確に同額で、符号が反転します。
delete_invoice	money	請求書を完全に削除します。Oblio では、シリーズ内の最後の番号の場合に限り削除できます。

Money

7 つの money ツールは tools/list でそのように示されており、クライアントは呼び出しごとに承認を求めます（Claude Code は、どの権限モードでもそうします）。MCP_CONFIRM=elicit を設定すると、代わりにサーバー自身が引数から生成した 1 行の確認文で尋ねます。例：

Issue invoice in series FCT to Client SRL (CIF RO87654329): 9680.00 RON incl. VAT 1680.00 (1 line), dated 2026-09-28, due 2026-10-28, marked paid by Ordin de plata OP 7001
Record 1000.00 EUR paid on invoice FCT 0042 to Client SRL, Ordin de plata OP 7001, 2026-10-02, leaving 210.00 EUR unpaid
Issue a reversing invoice for FCT 0042, Client SRL, total -9680.00 RON, in series FCT, keeping the payment recorded on it
DELETE invoice FCT 0042 totalling 9680.00 permanently (no undo; only the last number in a series can be deleted, and anything already sent to ANAF stays there)

最初の行は、以下のドキュメント入力に記載されています。最後の行は expect_total を指定した delete_invoice です。指定しない場合、この行には「合計金額が指定されていないため、確認されません」と表示されます。サーバーは先頭に名前を付けるので、oblio: Issue invoice ... のように読みます。

承認した内容がそのまま発行されます。

• 確認した合計金額が発行される合計金額です。 合計金額は documentTotal（キットの invoiceTotals.ts）で計算されます。これは create_invoice が computedTotal として返すものと同じ関数です。発行後にドキュメントを再取得し、Oblio の合計金額が異なる場合は、発行されたドキュメントを示す reason: "total_mismatch" を付けて呼び出しが失敗します。invoice_from_proforma は先にプロフォーマを読み取り、請求書の合計金額をその金額に合わせます。
• キャンセル、復元、削除では、先に請求書を読み取ります。 そのうえで、合計金額、Oblio が操作したドキュメント、会社の CIF を含む応答を返します。expect_total を指定した場合、合計金額が異なる請求書を指定しても何も変更されません。（Oblio のドキュメント読み取りには購入者情報が含まれないため、同じ方法で購入者を確認することはできません。）
• 支払いは請求書と照合されます。 サーバーは、キャンセル済みの請求書、すでに全額支払い済みの請求書、未払い残額を超える金額を拒否し、残額も通知します。

トラブルシューティング

auth："Oblio refused the client_id and secret"。 シークレットが変更されています。通常はパスワードのリセット後に発生します。Settings の Account Data から新しいシークレットをコピーし、app.json に設定してください。

発行または削除後に reason: "outcome_unknown" を伴う api。 接続が切断されたため、Oblio が操作を行ったかどうかは不明です。まずドキュメントを確認してください（get_invoice または Oblio のウェブアプリを使用します）。存在しない場合は、エラーで通知された idempotency_key を指定して再度呼び出してください。Oblio は同じキーで二度発行しません。collect_invoice の再実行はそのままで安全です。支払いが反映されていればそれを検出し、何も記録しません。

reason: "total_mismatch" を伴う api。 ドキュメントは発行されましたが、Oblio の合計金額が確認した金額と異なります。ドキュメントを開き（get_invoice または get_proforma を使用します）、誤りがあればキャンセルしてください。再発行はしないでください。

Oblio 独自のメッセージを伴う api（例："Seria FCT nu exista"）。メッセージには問題のあるフィールドまたはシリーズが示されます。list_series と list_vat_rates で Oblio が想定する名前を確認できます。

呼び出しでステータス 401 または 403 を伴う api。 アカウントには company_cif の会社に対する操作権限がありません。health と list_companies でアクセス可能な会社を確認できます。

reason: "drift" を伴う api。 Oblio の応答形式が変わりました。サーバーは推測による処理を拒否します。この問題を報告してください。

仕組み

ドキュメント入力

create_invoice と create_proforma では、Oblio の「Parametri document」テーブルを基にした、snake_case 形式の検証済み入力としてドキュメントを受け取ります。会社の CIF は含まれません。app.json から取得するため、貼り付けたサンプルによって別の会社宛てに発行されることはありません。

{
  "client": { "name": "Client SRL", "cif": "RO87654329", "vat_payer": true },
  "series_name": "FCT",
  "issue_date": "2026-09-28",
  "due_date": "2026-10-28",
  "currency": "RON",
  "products": [
    { "name": "Consulting", "price": "1000.00", "quantity": "8", "measuring_unit": "ora",
      "vat_name": "Normala", "vat_percentage": "21", "vat_included": false, "product_type": "Serviciu" }
  ],
  "collect": { "type": "Ordin de plata", "document_number": "OP 7001" }
}

• すべての金額は小数の文字列（"1000.00"）で指定し、パターンで検証したうえで文字列のまま Oblio に送信するため、浮動小数点数を経由することはありません。計算にはキットの厳密な decimal.ts を使います。
• 各明細では vat_included が必須です。Oblio のデフォルト（「含む」）では、税抜価格が暗黙のうちに税込価格に変換されるためです。確認する合計金額は vat_percentage を使って計算されるため、vat_percentage も必須です。
• 購入者のコードと IBAN はチェックディジットで検証されます。ルーマニアの購入者の cif は、有効なチェックディジットを持つ CIF または有効な CNP でなければならず、数字を入れ替えただけで別の会社宛てに請求書が送られることはありません。購入者の country が別の国の場合は、入力どおりに受け付けます。send_email を指定すると、Oblio が請求書を送信した宛先が応答の emailedTo に表示されます。
• シリーズと番号の形式を検証します。シリーズは list_series に示されるとおり、英字と数字で構成されます。番号はテキストとして数字のみで指定します（"0042"）。
• その他の不正な入力は、送信前にまとめて拒否されます（src/domain/rules.ts）。precision を超える小数桁（Oblio では暗黙に丸められます）、数量がゼロ、価格がマイナス、税率が 0～100 の範囲外、発行日より前の支払期限、領収書シリーズを指定していない Chitanta、参照情報を指定していないその他の支払いが該当します。
• 再試行によって二重発行されることはありません。 Oblio は、同じ idempotency_key を持つ 2 回目のドキュメントを拒否します。指定しない場合は、ドキュメント（種類、会社、内容、発行日）を基にキーを生成します（src/domain/keys.ts）。同じ日に意図的に同一のドキュメントを発行する場合は、独自のキーを指定してください。

合計金額

ANAF がすべての e-Factura に対して検証し、Oblio も準拠する EN 16931 の規則では、明細金額は数量に価格を掛けて小数第 2 位に丸めます。VAT は、同じ税率の金額の合計に対して税率ごとに一度だけ計算します（同じ税率の税込明細と税抜明細は別々のグループとして、それぞれ一度だけ丸めます）。合計は明細金額と VAT の合計です。税込総額に含まれる VAT は、総額 × 税率 ÷（100 ＋ 税率）で求めます。端数処理はすべて、PHP の round() と同じ、ゼロから遠ざかる方向への丸めです。この丸め方法は対称的であるため、ストルノの明細を合計すると、元の合計金額と正確に一致する符号反転値になります。テストでは丸めが発生するケースを検証しています。

支払いと取り消し

collect_invoice は請求書のシリーズと番号、支払い方法（銀行振込の場合は Ordin de plata、Card、領収書付きの現金払いの場合は Chitanta、および Oblio のその他の種類）、金額、日付、支払いの参照情報を受け取ります（領収書の場合は Oblio が番号を付けるため、代わりにシリーズを指定します）。Oblio は金額を請求書の合計額、日付を今日の日付として自動設定できますが、これらを確認せずに確定すべきではないため、金額と日付は必須です。まず請求書を読み込むため、確認する明細の購入者と通貨は請求書に記載されたものになり、回答には処理前後の残高が表示されます。同じ呼び出しを繰り返すと、支払いがすでに反映されていればそれを見つけ、何も記録しません。種類、参照情報、金額、日付が同じ支払いをもう一度記録するには、独自の idempotency_key を指定してください。支払いは Oblio の Web アプリで削除します。このサーバーでは取り消せません。

reverse_invoice は Oblio 独自の参照フローを使うため、ストルノと元の請求書が Oblio 内で関連付けられ、再入力は不要です。請求書全体を取り消します。一部を修正する場合は、create_invoice で修正用の請求書を発行してください。storno_series でシリーズを選択します（デフォルトは元の請求書のシリーズです）。remove_payments では、元の請求書に記録された支払いを残す（別途返金する場合のデフォルト）か、削除する（Oblio の refund）かを指定します。キャンセル済みの請求書と、それ自体が取り消しである請求書は拒否されます。冪等性キーは取り消し対象の請求書から取得されるため、何日後に再試行しても、2回目のストルノは発行されません。意図的にもう一度取り消すには、最初の取り消しをキャンセルした後、独自のキーを指定してください。

請求書の一覧表示

list_invoices は各請求書について、シリーズと番号、日付、通貨、Oblio が記録した合計額、キャンセル済みかどうか、購入者、支払い、e-Factura の状態、PDF リンクを返します。購入者を名前で探すには、list_clients で検索し、その CIF で絞り込んでください。

• unpaid と paid は Oblio の「回収済み」フラグに従い、キャンセル済みの請求書を除外します。cancelled ではキャンセル済みの請求書だけを一覧表示します。下書きは一覧に表示されません。
• Oblio は各請求書の e-Factura の状態（not_sent、processing、sent、errors）を返しますが、この状態では絞り込めません。そのため、このフィルターは Oblio の回答後、各ページに適用されます。絞り込み後のページには、読み込んだ行数（scanned）が示されます。行が1件もなくても次のページがある場合があるため、nextCursor をたどり続けてください。
• 1ページには最大100行が含まれます。カーソルには最後に読み込んだ行が記録されるため、ページの取得中に請求書が発行されても、同じ行が繰り返されることはありません。異なるフィルターと併用されたカーソルは拒否されます。

失敗から分かること

サンドボックスはないため、失敗から何が分かるかによって、呼び出しを再試行するかどうかが決まります（キットの makeHttp を使う src/infra/http.ts）。

• 429 は何も起きていないことを示します。すべての呼び出しが Retry-After に従って再試行されます。
• 新しいトークンでの401：トークンを一度再発行し、2回目の401はそのまま受け入れます。
• 接続の切断または5xx では、何が起きたかは分かりません。読み取り、キャンセル、復元は再試行されます。発行と削除は再試行されず、outcome_unknown として失敗します（トラブルシューティングを参照）。

Oblio は、ドキュメントについては100秒あたり30リクエスト、それ以外については10秒あたり30リクエストに制限しています。サーバーはどちらの制限も下回るようにペースを調整します（src/infra/http/throttle.ts：同時に10件、その後、発行では5秒ごとに1件、それ以外では毎秒2件）。そのため、集中したリクエストは429になる代わりに待機します。HTTP経由では、プロセス内のすべてのクライアントに対してペース調整が適用されます。

返される内容

Oblio は OpenAPI も JSON Schema も公開しておらず、SDK に型も含まれていないため、ワイヤー上の型は https://www.oblio.eu/api および PHP SDK の OblioSoftware/OblioApi@027a5cc を参照しながら、src/domain/schema.ts で手作業でモデル化しています。すべてのレスポンスは境界でこれらの型に照らして解析されます。ドキュメントに記載されたフィールドが欠落している場合、呼び出しは drift として失敗し、そのまま処理が続くことはありません。また、ドキュメントに記載されていないフィールドは破棄されます。フラグは、Oblio が true、1、"1" のどれを送信してもブール値になります。小数は Oblio が書き込んだ文字列のままです。シリーズ番号はテキスト（"0051"）のままです。api の失敗では、Oblio 自身の statusMessage を最初に示します。「Seria FCT nu exista」が回答のすべてだからです。

npx tsx scripts/smoke.ts は、認証情報を使ってビルド済みサーバーを実行します。--write-proforma <series> を指定しない限り読み取り専用で、指定すると 0.01 のプロフォーマを 1 件発行します。ここから money にアクセスすることはできません。

制限事項

• サーバーごとに会社は 1 社のみ：会社の CIF は app.json にあります。複数の会社に紐づくアカウントでは、会社ごとに設定が必要です。
• e-Factura の送信は行いません。 ANAF への請求書送信は別の処理です。送信には anaf-efactura サーバーを使用します。
• 納品書は対象外であり、納品書から作成する請求書も対象外です。
• Oblio のドキュメントに記載されたフィールドの一部は、意図的に含めていません。：

Oblio field	Why not
割引行（discount、discountType、discountAllAbove）	Oblio は、金額割引に VAT が含まれるか、どのように丸められるかを記載していないため、確定する合計額を正確に計算できません。割引は行の価格に含めてください。
商品の currency、exchangeRate	別通貨の行は、合計額に意味を持たせる前に Oblio による換算が必要です。行の通貨にはドキュメントの通貨が使われます。
disableAutoSeries、number	手動で採番すると、会計シリーズに欠番や重複が生じるおそれがあります。Oblio が採番します。
create_invoice の referenceDocument	参照は、独自の確認行を伴う別の処理です。ストルノは reverse_invoice、プロフォーマは invoice_from_proforma で処理します。
clientLocation（BT-71～BT-80）、deputyName、deputyIdentityCard、deputyAuto、selesAgent、noticeNumber	商品配送に関するフィールドです。配送先、代理人、車両、販売員、納品書を表します。
issuerId	発行者の個人識別番号（CNP）であり、請求書には不要です。issuer_name は使用します。
receptionNotice、projectNumber、buyerIdentifier、clientAccountReference、contractNumberDate	Oblio の表では、最初の 3 つの e-Factura フィールド番号がずれて記載されているため、どのフィールドに対応するかが不明です。残り 2 つには e-Factura フィールドがありません。order_number（BT-13）と contract_number（BT-12）は使用します。
spvExtern	ANAF への送信は別の処理です（上記参照）。
codeClient、codeEAN、nameTranslation、measuringUnitTranslation	カタログおよび翻訳用のフィールドです。商品の name と code は使用します。

list_invoices では、Oblio の withProducts（一覧に表示される行の形式が記載されていないため、検証できません）、および id と number のフィルター（get_invoice はシリーズと番号を指定して 1 件のドキュメントを取得します）は使用しません。

Oblio 向けのその他のサーバー

2026-10-15 に調査しました。Oblio は MCP サーバーを公開していません。GitHub アカウントでは PHP、Node、Python、Go、Java、C# 用の API クライアントとショッププラグインを提供しており、サイトにも MCP の記載はありません。2 つのコミュニティ製サーバーは、このサーバーよりも多くの Oblio API をカバーしています。

• oblio-mcp（GitHub、npm にはありません）：stdio のみ対応し、メールアドレスと API シークレットを環境変数に設定します。会社は実行時に set_cif で選択します。納品書を含むすべての書類種別、書類一覧、支払い、e-Factura の送信に対応しています。
• MCP レジストリの io.usefulapi/oblio：Oblio の認証情報を保持する第三者の OAuth サインインを介して HTTP でホストされています。対応範囲は同程度で、ウェブフックにも対応しています。月 100 回までは無料で、それ以降は有料です。

このサーバーは、ほかのどのサーバーも行わない機能のために存在します。ANAF が e-Factura の検証に使う規則に従って請求書の合計額を計算し、その合計額を確認した明細行に設定して、発行された書類と照合します。呼び出し元が冪等性キーを指定しない場合はキーを生成し、再試行しても二重発行されないようにします。ルーマニアの購入者の CIF または CNP をチェックディジットで検証します。設定で指定された 1 つの会社だけを対象とします。また、クライアントが読み取ることのないファイルにシークレットを保存し、独立したサービスとして実行できます。e-Factura は送信しません。