MCP Holded

MCP Holded

Holded 向けの Model Context Protocol サーバー（v2 API 対応）

コミュニティプロジェクトです。Holded との提携、同社による承認やサポートはありません。「Holded」と Holded のロゴはそれぞれの所有者の商標であり、このサーバーが接続する API を示す目的で使用しています。

Holded API v2 向けの MCP サーバーです。連絡先、売上および仕入れ関連の書類、支払い、資金管理、会計、カタログ、チーム、CRM、プロジェクト、カレンダー、受信箱、ウェブフックに対応しています。action パラメーターを使う階層型ツールを13個備え、すべてのリクエストとレスポンスを Zod で検証します。読み取り時にはリトライし、破壊的な操作にはすべて確認ゲートを設けています。

Holded は従来の API（/api/invoicing/v1、key ヘッダー）を非推奨にしました。新しいキーの形式は pat_<id>_<secret> で、v2（https://api.holded.com/api/v2、Authorization: Bearer）でのみ認証できます。このサーバーは v2 のみを使用します。

このサーバーを選ぶ理由

• 現在も利用できる API である v2 のみを使用します。 Holded は従来の API（/api/invoicing/v1、key ヘッダー）を非推奨にしました。新しいトークンは pat_<id>_<secret> 形式で、v2 でのみ認証できます。このサーバーが使用するのは v2 のみです。
• action パラメーターを使う階層型ツールを13個備えています。 エンドポイントごとにツールを用意するのではなく、モデルのコンテキスト内でツール一覧を小さく保ちながら、連絡先、売上、仕入れ、支払い、資金管理、会計、カタログ、チーム、CRM、プロジェクト、カレンダー、受信箱、ウェブフックを網羅します。
• MCP リソースを7個、MCP プロンプトを6個備えています。 リソースには、アカウント固有の税区分キー、採番系列、支払い方法、勘定科目表のほか、スキーマでは表現できない API の動作情報が含まれます。プロンプトは、売掛金の滞留分析、VAT の概要、銀行口座の照合、明細書、月次決算といった実際のワークフローを実行します。
• 破壊的な操作にはすべて確認ゲートを設けています。 構造テストにより、文書に記載された一覧とコードが一致していることを確認します。削除、上書き、承認、メール送信を行う操作は、confirm: true がなければ実行されません。
• すべてのリクエストとレスポンスを Zod で検証します。 サーバーが認識していない形式は、何も通知されずに成功するのではなく、明確なスキーマエラーとして示されます。
• 匿名化された実際の v2 レスポンスを使ったテストを200件以上備えています。 信頼された公開による npm の来歴情報にも対応し、Node 18 以降で動作します。

比較

npm には Holded 向けの MCP サーバーが4つあります。ここでは説明文ではなく、公開されているコードを比較しています（2026-09-08 時点）：@t4dhg/mcp-holded 2.1.1、@nubiia/mcp-holded 2.0.2、@energio/holded-mcp 1.5.1、holded-mcp 1.0.0。これは特定時点での比較で、時間とともに古くなります。利用する前に、最新バージョンをご自身で確認してください。

	@t4dhg/mcp-holded	@nubiia/mcp-holded	@energio/holded-mcp	holded-mcp
API バージョン	v2	v2	v1（非推奨）	v1（非推奨）
認証	Bearer pat_	Bearer pat_	key ヘッダー	key ヘッダー
対応ドメイン	13	18 個のツールモジュールファイル（カレンダー、予約、受信トレイ、ウェブフック、CRM は含まれません）	5 つの API セクション（会計、CRM、請求、プロジェクト、チーム）	5 つの API セクション（会計、CRM、請求、プロジェクト、チーム）
ツールの形式	13 個の階層型、action パラメーター（ツール合計 15 個）	119 個のフラットなツール、操作ごとに 1 つ	139 個のフラットなツール、操作ごとに 1 つ	136 個のフラットなツール、操作ごとに 1 つ
MCP リソース	7	0	0	0
MCP プロンプト	6	0	0	0
破壊的操作の制限	すべてに適用され、構造的にテスト済み	確認ゲートなし。destructiveHint アノテーションとツールごとのレート制限のみ	確認ゲートなし。destructiveHint アノテーションのみ	確認ゲートなし。destructiveHint アノテーションのみ
レスポンスの検証	Zod、リクエストとレスポンス	Zod、リクエストのみ	Zod、リクエストのみ	Zod、リクエストのみ
Node の最小バージョン	18	22.14	20	18
テスト	234	23 ファイルにわたる 389 件。パッケージに同梱され、すべて合格済み	同梱なし	同梱なし
npm の来歴	あり	あり	なし	なし
ライセンス	MIT	MIT	MIT	MIT
最終公開日	2026-09-08	2026-07-07	2026-07-01	2026-02-25
最も大きな違いは、v1 サーバーが Holded によって非推奨となった API を使用しており、新しい pat_ トークンではその API にまったく認証できないため、新たに発行されたキーでは動作しないことです。現行の @nubiia/mcp-holded と比べると、違いは対応範囲（このサーバーはカレンダーと予約、受信トレイ、Webhook、CRM のリードとファネルをカバーしており、nubiia のツール一覧にはこれらがありません）、リソースとプロンプトの対応範囲、階層型のツール構成、そして条件付きの生リクエスト用の代替手段です。nubiia が独自に求める Node の最低バージョンは 22.14 で、このサーバーと holded-mcp がどちらも対応する 18 より実際に高くなっています。

クイックスタート

インストールは不要です。以下のクライアントはすべて、npx を通じてサーバーを実行します。Holded の Settings, Developers, API でトークンを作成し、pat_..._... の値全体を使用してください。

Claude Desktop

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-holded"],
      "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
    }
  }
}

Claude Code

claude mcp add holded --env HOLDED_API_KEY=pat_xxxxxxxx_xxxxxxxx -- npx -y @t4dhg/mcp-holded

Cursor

すべてのプロジェクトで使用する場合は ~/.cursor/mcp.json、1 つのプロジェクトで使用する場合は .cursor/mcp.json を編集します。

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-holded"],
      "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
    }
  }
}

VS Code

.vscode/mcp.json を編集します。キーは mcpServers ではなく servers であることに注意してください。

{
  "servers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-holded"],
      "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
    }
  }
}

Node.js 18 以降が必要です。

環境変数

変数	必須	デフォルト	用途
HOLDED_API_KEY	はい	なし	v2 Personal Access Token。v1 キーは起動時に拒否されます。
HOLDED_BASE_URL	いいえ	https://api.holded.com/api/v2	テスト用に API ベースを上書きします。
HOLDED_TIMEOUT_MS	いいえ	30000	リクエストごとのタイムアウトです。
HOLDED_MAX_RETRIES	いいえ	3	GET リクエストの試行回数です。書き込みは再試行されません。
DEBUG	いいえ	false	リクエストを stderr に記録します。

利用例

未払い請求書の確認。 holded_aged_receivables プロンプトを実行します。未払いの請求書が、支払期限からの経過期間別、顧客別にまとめられ、遅延が深刻な順に表示されます。一部入金済みの請求書は、未払い残額のみが計上されます。次に holded_contact_statement で最も滞納している顧客の明細書を作成すれば、そのまま送付できる形式で受け取れます。

銀行取引の月次照合。 対象期間について holded_bank_reconciliation を実行します。金額と日付を基準に、銀行の入出金と記録済みの支払いを照合し、重要な 2 つの一覧を表示します。支払いが記録されていない入出金と、銀行明細に記載されていない支払いです。照合には確認が必要なため、承認するまで帳簿上では何も照合されません。

四半期の VAT 数値の準備。 holded_vat_summary を実行します。四半期の売上と仕入れを税区分ごとにまとめ、各区分の課税標準額と税額を表示します。これは Modelo 303 が求める形式です。申告用ではなく、作業を補助するためのものです。その旨も明記されています。

月次締め。 holded_month_end_close を実行します。まだ下書きのままのもの、支払期限を過ぎたもの、受信トレイに残っているものを、それぞれ解決するための正確な呼び出しとともに表示します。

ツール

すべてのツールは action を受け取ります。一覧取得アクションでは limit（1〜200）と cursor を指定でき、レスポンスに続きの取得方法が示されます。作成および更新アクションでは、Holded v2 のリクエスト仕様に従ったペイロードを data に指定し、API から再取得したレコードが返されます。確認が必要なアクションでは confirm: true を指定します。

ツール	アクション
holded_discover	以下のドメインを一覧表示します。
holded_contacts	list（完全一致フィルター email、code、phone、mobile、custom_id）、search（name の部分一致）、get、create、update、delete、bulk_archive、bulk_delete、list_attachments、attach（file_path）、portal_link、list_groups、get_group、create_group、update_group、delete_group
holded_sales	type は invoice、credit_note、estimate、proforma、sales_receipt、sales_order、waybill、receipt_note、recurring_invoice のいずれかです。list（contact_id、status、start_date、end_date、due_date_start、due_date_end、sort、approval_status）、get、find_by_number、pdf（output_path）、list_attachments、attach、schedule、create、update、delete、approve、cancel、send、set_pipeline、record_payment、convert、accept、reject、skip、bulk_approve、bulk_cancel、bulk_delete
holded_purchases	type は purchase、purchase_refund、purchase_order、purchase_shipment のいずれかです。list（同じフィルター）、get、pdf、list_attachments、attach、received_items、create、update、delete、approve、send、set_pipeline、record_payment、receive
holded_payments	list（start_date、end_date、banking_account_id、document_id）、get、create、update、delete、list_methods、get_method
holded_treasury	list_accounts（type、archived）、get_account、create_account、update_account、archive_account、delete_account、list_movements（start_date、end_date）、list_cash_movements、create_movements、reconcile（movement_id）、list_remittances、get_remittance、list_forecasts、get_forecast、create_forecast、update_forecast、delete_forecast
holded_accounting	list_accounts（start_date と end_date を指定すると借方、貸方、残高を追加、include_empty）、create_account、list_ledger（start_date と end_date が必須、account）、create_ledger_entry、list_taxes、tax_keys、list_expenses_accounts、get_expenses_account、create_expenses_account、update_expenses_account、delete_expenses_account、list_sales_channels、get_sales_channel、create_sales_channel、update_sales_channel、delete_sales_channel、list_numbering_series（series_type）、create_numbering_series、update_numbering_series、delete_numbering_series、list_tags、create_tag、delete_tag
holded_catalog	list_products（name）、get_product、product_stock、create_product、update_product、update_stock、delete_product、list_services、get_service、create_service、update_service、delete_service、list_warehouses、get_warehouse、warehouse_stock、create_warehouse、update_warehouse、delete_warehouse、list_price_lists、get_price_list、create_price_list、update_price_list、delete_price_list、list_production_orders、get_production_order、create_production_order、update_production_order、delete_production_order
holded_team	list_employees（search）、get_employee、employee_contract、create_employee、list_times、list_salary_records（employee_id、start_date、end_date）、get_salary_record、salary_record_pdf、list_payslips、get_payslip、payslip_pdf、create_payslip_payment、delete_payslip_payment
holded_crm	list_funnels、get_funnel、create_funnel、update_funnel、delete_funnel、list_leads、get_lead、create_lead、update_lead、delete_lead、move_stage、update_dates、add_note、update_note、add_task、update_task、delete_task
holded_projects	list_projects（status）、get_project、project_summary、create_project、update_project、delete_project、list_tasks、get_task、create_task、update_task、delete_task、list_times、get_time、create_time、update_time、delete_time
holded_calendar	list_events、get_event、create_event、update_event、delete_event、list_bookings、get_booking、create_booking、update_booking、cancel_booking、list_locations、slots
holded_inbox	list（status、start_date、end_date、user_id）、get、upload（file_path）、download（filename、output_path）、update、attach、delete
holded_webhooks	list、get、events、create、update、enable、disable、delete、usage
holded_request	任意の v2 エンドポイント：method、path、query、body。以下を参照してください。

例

{
  "action": "list",
  "type": "invoice",
  "status": "pending",
  "start_date": "2026-01-01",
  "sort": "-date",
  "limit": 50
}

{
  "action": "create",
  "type": "invoice",
  "data": {
    "contact_id": "5ff44eb88ec0b10f326e3213",
    "date": "2026-09-06",
    "items": [{ "name": "Licence", "units": 1, "price": 1000, "taxes": ["s_iva_21"] }]
  }
}

リソース

7 つの MCP リソースが、モデルが正しい呼び出しを行うために必要なコンテキストを提供します。クライアントにアタッチするか、URI で読み取ってください。

URI	内容
holded://guide/api-behaviour	検証済みの v2 の挙動：Bearer 認証と 401 ではなく 403 が返される特異な仕様、カーソルページネーション、2 種類の小数表記規則、DD/MM/YYYY 形式の台帳日付、RFC 7807 エラー、黙って無視されるクエリパラメーター、1 分あたり 100 リクエストの上限、書き込みが再試行されない理由。
holded://guide/document-types	販売用 9 種類と仕入用 4 種類の文書タイプと、それぞれのスペイン語名、および各タイプがサポートする動詞。定期請求書、仕入れの返金、見積書には、それぞれ他のタイプにはある動詞がありません。
holded://guide/irreversible-operations	リスクと影響を含む、承認が必要なすべての操作。ポリシーテーブルから生成されるため、内容がずれることはありません。また、Verifactu では販売伝票の承認を取り消せない理由も記載しています。
holded://reference/taxes	アカウントの税キー、名称、税率。文書の明細には、たとえば s_iva_21 のように、キーをそのまま指定する必要があります。
holded://reference/numbering-series	文書タイプごとに設定された採番シリーズと、その形式および最後に使用された番号。
holded://reference/payment-methods	record_payment と、文書の payment_method_id に必要な支払い方法 ID。
holded://reference/accounting-accounts	仕訳に必要な勘定科目表。推測できないスペインの PGC 番号体系を使用します。

3 つのガイドは静的です。4 つのリファレンスはアカウント独自の設定を読み取り、クライアントが会話の開始時に毎回リソースを読み直すため、15 分間キャッシュされます。リファレンスの読み取りに失敗した場合は、代わりに使用するツールと説明が返され、例外はスローされません。

プロンプト

このサーバーが提供するワークフローを実行するのは、6 つの MCP プロンプトです。それぞれ、事前に情報を読み込み、レポートと実行に必要な正確なツール呼び出しを返します。**どれも書き込みは行いません。**変更が必要な場合、プロンプトは承認を求めるゲート付きの呼び出しを提示します。

プロンプト	引数	内容
holded_aged_receivables	as_of, contact_id	未払いの売上請求書を、支払期限超過日数で分類し、取引先ごとにまとめて、超過日数が多い順に表示します。書類の合計額ではなく、未払い残高を集計します。
holded_vat_summary	start_date, end_date	期間内の仕入 VAT と売上 VAT を、税区分キーごとに課税標準額と税額とともに出力します。Modelo 303 の作成に役立つ資料であり、申告書ではなく、税務アドバイスでもありません。既定では直前の暦四半期が対象です。
holded_bank_reconciliation	start_date, end_date, account_id	銀行取引と記録済みの支払いの照合候補を提示し、両側で未照合の項目を一覧表示します。既定では前月が対象です。
holded_contact_statement	contact_id or name	1 件の取引先について、請求額、支払額、未払い額を書類ごとに表示し、最も古い未払い項目を明示します。API が書類の未払い額を返さない場合は、合計額から支払額を差し引いて算出し、どの行が算出値なのかを示します。
holded_month_end_close	start_date, end_date	期間終了時点で未処理の項目を表示します。下書きの書類、支払期限を過ぎた請求書、受信トレイ内の書類を、それぞれ解決するための呼び出しとともに示します。
holded_draft_invoice	contact, description, date	取引先を特定し、売上書類で使用できる税区分キーのみを提示して、確認用の作成ペイロードを組み立てます。作成は行わず、承認することもありません。

安全性

確認が必要な操作

これらの操作は、何かを削除、上書き、ロック、またはメール送信します。confirm: true を指定しない場合、ツールは何も送信せず、実行すると何が起きるかを説明します。同じ呼び出しに confirm: true を指定すると、操作が実行されます。構造テストにより、この一覧がコード内のゲート付き操作と一致することが保たれています。

• holded_contacts({ action: 'update' })、holded_contacts({ action: 'delete' })、holded_contacts({ action: 'bulk_archive' })、holded_contacts({ action: 'bulk_delete' })、holded_contacts({ action: 'update_group' })、holded_contacts({ action: 'delete_group' })
• holded_sales({ action: 'update' })、holded_sales({ action: 'delete' })、holded_sales({ action: 'approve' })（法定番号を割り当てます。Verifactu では取り消せません）、holded_sales({ action: 'cancel' })、holded_sales({ action: 'send' })（顧客にメールを送信します）、holded_sales({ action: 'set_pipeline' })、holded_sales({ action: 'skip' })、holded_sales({ action: 'bulk_approve' })、holded_sales({ action: 'bulk_cancel' })、holded_sales({ action: 'bulk_delete' })
• holded_purchases({ action: 'update' })、holded_purchases({ action: 'delete' })、holded_purchases({ action: 'approve' })、holded_purchases({ action: 'send' })、holded_purchases({ action: 'set_pipeline' })
• holded_payments({ action: 'update' })、holded_payments({ action: 'delete' })
• holded_treasury({ action: 'update_account' })、holded_treasury({ action: 'archive_account' })、holded_treasury({ action: 'delete_account' })、holded_treasury({ action: 'reconcile' })、holded_treasury({ action: 'update_forecast' })、holded_treasury({ action: 'delete_forecast' })
• holded_accounting({ action: 'update_expenses_account' })、holded_accounting({ action: 'delete_expenses_account' })、holded_accounting({ action: 'update_sales_channel' })、holded_accounting({ action: 'delete_sales_channel' })、holded_accounting({ action: 'update_numbering_series' })、holded_accounting({ action: 'delete_numbering_series' })、holded_accounting({ action: 'delete_tag' })
• holded_catalog({ action: 'update_product' })、holded_catalog({ action: 'update_stock' })、holded_catalog({ action: 'delete_product' })、holded_catalog({ action: 'update_service' })、holded_catalog({ action: 'delete_service' })、holded_catalog({ action: 'update_warehouse' })、holded_catalog({ action: 'delete_warehouse' })、holded_catalog({ action: 'update_price_list' })、holded_catalog({ action: 'delete_price_list' })、holded_catalog({ action: 'update_production_order' })、holded_catalog({ action: 'delete_production_order' })
• holded_team({ action: 'delete_payslip_payment' })
• holded_crm({ action: 'update_funnel' })、holded_crm({ action: 'delete_funnel' })、holded_crm({ action: 'update_lead' })、holded_crm({ action: 'delete_lead' })、holded_crm({ action: 'move_stage' })、holded_crm({ action: 'update_dates' })、holded_crm({ action: 'update_note' })、holded_crm({ action: 'update_task' })、holded_crm({ action: 'delete_task' })
• holded_projects({ action: 'update_project' })、holded_projects({ action: 'delete_project' })、holded_projects({ action: 'update_task' })、holded_projects({ action: 'delete_task' })、holded_projects({ action: 'update_time' })、holded_projects({ action: 'delete_time' })
• holded_calendar({ action: 'update_event' })、holded_calendar({ action: 'delete_event' })、holded_calendar({ action: 'update_booking' })、holded_calendar({ action: 'cancel_booking' })
• holded_inbox({ action: 'update' })、holded_inbox({ action: 'attach' })、holded_inbox({ action: 'delete' })
• holded_webhooks({ action: 'update' })、holded_webhooks({ action: 'disable' })、holded_webhooks({ action: 'delete' })

作成操作はゲートの対象外です。これには record_payment、create_movements、create_ledger_entry が含まれます。これらは後から削除できるレコードを追加します。ゲートは誤操作を減らすためのものであり、認可境界ではありません。また、トークンには Holded が許可するすべての操作権限が付与されます。

生リクエストツール

holded_request は、正しい Bearer 認証を使ってすべての v2 エンドポイントにアクセスし、検証を行わずにレスポンスを返します。DELETE、PUT、PATCH では confirm: true が必要です。また、Holded では破壊的な操作が隠されているため、パスに bulk、cancel、archive、approve、send、reconcile、ship、skip、clock-in、clock-out のいずれかを含む POST にも confirm: true が必要です。拒否された呼び出しでは、送信されるはずだったメソッド、URL、本文がそのまま返されます。

API の実際の動作

以下はすべて、2026-09-06 に稼働中の v2 レスポンスで検証した内容であり、スキーマの根拠となっています。

• ページネーションはカーソルベースです。 リストは { items, cursor, has_more } を返します。cursor は最後の項目の ID で、?cursor= として渡します。limit のデフォルトは 50、上限は 200 です。page と offset は無視されます。設定リスト（税、タグ、倉庫、会計勘定、費用勘定、販売チャネル、採番系列、価格表、予約場所）は、カーソルなしで { items } を返します。
• 金額は文字列で、形式は 2 種類あります。 販売・仕入書類、その明細、給与記録ではカンマを使います（"63500,00"）。支払い、資金管理勘定、銀行取引、会計勘定、元帳仕訳ではドットを使います（"8.3"、"0.00"）。サーバーは値を変換せずそのまま渡すため、丸め処理は行われません。
• 元帳の日付は DD/MM/YYYY 形式です。 それ以外はすべて ISO 8601 形式です。
• エラーは RFC 7807（{ type, title, status, detail }）形式で、400、403、404 を返します。キーが無効または未指定の場合は、401 ではなく 403 "Access denied" が返ります。不明なルートでは 404 { message: "No route found..." } が返ります。不正なパスの中には、Holded の HTML アプリシェルを 200 または 405 で返すものがあります。その場合、サーバーは HTML を返さず、エラーに変換します。
• 文書化されていないクエリパラメーターは黙って無視されます。 /contacts の query、q、search はフィルターとして機能しません。search（/contacts/search?name= を呼び出します）または完全一致フィルターを使用してください。
• 書類の ID 指定取得では、リスト取得より多くの情報が返ります。 accounting_date、approved_at、notes、language、payments_detail、payments_refunds、shipping、design_id、pipeline_id などが含まれます。
• すべての書類種別で、すべての HTTP メソッドが使えるわけではありません。 仕入返金は /purchase-refunds でリスト表示されますが、読み取りと作成には /purchases/refund を使い、ほかの操作（更新、削除、PDF、添付ファイル、承認）はありません。仕入には PDF と送信のルートがありません。定期請求書で利用できるのは、更新、削除、スキップ、スケジュール設定のみです。見積書、仮請求書、注文書、送り状には支払い機能がありません。ツールは、サポートされていない組み合わせを送信前に拒否し、利用可能な操作を列挙したメッセージを返します。
• 採番系列の種別は invoice、purchase、estimate、creditnote、salesorder、waybill、salesreceipt、purchaserefund です。
• レート制限は、キーごとに 1 分あたり 100 リクエストです。GET は、429（Retry-After に従います）、5xx、タイムアウト、ネットワークエラーの場合に、指数バックオフとジッターを使って再試行します。Holded にはべき等キーがないため、書き込みは必ず 1 回だけ送信されます。
• 作成処理は 201 と { id } を返します。 サーバーはレコードを再取得し、ツールは検証済みのオブジェクトを返します。
• CRM リード、プロジェクト、タスク、イベント、予約、Webhook、給与明細、価格表、製造注文、販売注文、販売レシート、入荷伝票、仕入出荷、送金のスキーマは、検証に使用したアカウントにレコードがなかったため、稼働中のレコードではなく OpenAPI ドキュメントを基にしています。これらは許容範囲の広いオブジェクトで、追加フィールドもそのまま渡されます。不一致があれば、成功したように見せかけず、明確なスキーマエラーとして表面化します。

トラブルシューティング

キーに関するメッセージが表示され、サーバーがすぐに終了する

HOLDED_API_KEY には、pat_<id>_<secret> 形式の v2 Personal Access Token を指定する必要があります。サーバーは起動時にこれを確認し、後続のすべての呼び出しが失敗する事態を避けるため、形式が異なる場合は実行を拒否します。従来の v1 キーは 32 文字の 16 進数で、v2 では認証に使えません。

すべての操作で「403 Access denied」が返される

v2 でトークンが無効、失効済み、またはスコープが正しくない場合に起こります。Holded は 401 ではなく 403 を返すため、認証の問題であることが多いにもかかわらず、権限の問題のように見えます。Holded の「Settings」から「Developers」、「API」の順に開き、トークンを再生成してください。また、両方のアンダースコアを含め、pat_..._... の値全体をコピーしたことを確認してください。

ドキュメントの種類では利用できない操作だとツールに表示される

すべての種類で、すべての操作ができるわけではありません。仕入返品では、更新、削除、PDF、添付ファイル、承認はできません。仕入では、PDF と送信はできません。定期請求書でできるのは、更新、削除、スキップ、スケジュール設定のみです。見積書、プロフォーマ、受注書、納品書では、支払いはできません。ツールはリクエストを送る前に処理を拒否し、利用可能な操作を一覧表示します。全種類の一覧は holded://guide/document-types リソースにあります。

フィルターが無視されているように見える

おそらく実際に無視されています。Holded はドキュメントに記載されていないクエリパラメーターを通知なく無視します。/contacts の query、q、search は何も絞り込まず、すべてを返します。/contacts/search?name= を呼び出す search アクションを使うか、完全一致で絞り込む email、code、phone、mobile、custom_id を使ってください。page と offset はどこでも無視されます。ページネーションには cursor を使います。

リソースを読み取れなかったと表示される

4 つの holded://reference/... リソースは設定をリアルタイムで読み取るため、有効なトークンが必要です。例外をスローせず、説明を返すため、サーバーの動作は継続します。3 つの holded://guide/... リソースは静的で、常に読み取れます。

DEBUG=true を設定する

すべてのリクエストが stderr にログ出力されるようになります。MCP のトランスポートである stdout には、決して出力されません。

FAQ

古い v1 API キーでも動作しますか？ いいえ。意図的に対応していません。v1 は非推奨で、新しいキーでは認証できません。両方をサポートすると、片方が行き止まりとなる 2 つのコードパスが必要になります。

誤ってデータを削除してしまうことはありますか？ 削除、上書き、承認、キャンセル、メール送信を行う操作には、すべて confirm: true が必要です。これがなければ、ツールは何も送信せず、実行しようとしていた操作を伝えます。操作の一覧はコードから生成され、holded://guide/irreversible-operations にあります。ドキュメントとコードの一覧が一致しない場合、テストは失敗します。

書き込みがタイムアウトした場合はどうなりますか？ 再試行はされません。Holded には冪等性キーがないため、書き込みを再試行すると二重請求や二重発行につながる可能性があります。読み取りはバックオフ付きで再試行しますが、書き込みは正確に 1 回だけ送信します。書き込みがタイムアウトした場合は、再試行する前にレコードを読み取ってください。

請求書の承認に確認が必要なのはなぜですか？ 法的な請求書番号が割り当てられるためです。Verifactu では、これは変更できない一連の記録の一部となり、取り消せません。誤りがあった場合は編集ではなく、クレジットノートが必要です。

金額は往復しても安全ですか？ はい。金額は文字列であり、サーバーはそのまま受け渡すため、丸められることはありません。ただし、表記には 2 つの規則があります。ドキュメントと給与記録ではカンマを使い、支払い、資金管理、会計ではピリオドを使います。

専用アクションのないエンドポイントにもアクセスできますか？ はい。holded_request を使うと、正しい認証情報で v2 の任意のパスにアクセスできます。破壊的なメソッドとパスにも、同じく制限が適用されます。

Holded と提携していますか？ いいえ。Holded の公開 API を利用するコミュニティプロジェクトです。

開発

npm install
npm run lint && npm run typecheck && npm run format:check && npm test && npm run build
HOLDED_API_KEY=pat_..._... npm run smoke   # spawns the built server over stdio and makes one read call

テストでは src/__tests__/fixtures にある匿名化済みのフィクスチャを使います。各フィクスチャは実際の v2 レスポンスで、名前、税 ID、住所、銀行口座の詳細、金額が置き換えられています。エンドポイントを追加する際はフィクスチャも追加してください。スキーマが設定されていないフィクスチャがあると、スキーマテストは失敗します。

リリース

リリースは CI でステージングされ、人が昇格させます。package.json のバージョンを上げてコミットし、vX.Y.Z のタグを付けて、そのタグをプッシュしてください。公開ワークフローでは、信頼されたパブリッシャーとして OIDC で npm に認証します（トークンはどこにもありません）。テストとビルドを実行し、npm stage publish を実行します。メンテナーがローカルで npm stage approve <stage-id> を実行するまでは、インストールできません。このときに 2FA が確認されます。詳しい手順については、CONTRIBUTING.md を参照してください。

Security

Report vulnerabilities through GitHub Security Advisories; see SECURITY.md.

License

MIT