mcp-holded

MCP Holded

Holded API 用の Model Context Protocol（MCP）サーバーです。このサーバーを使うと、Claude などの AI アシスタントが Holded の請求、会計、連絡先、製品、財務、人事、時間追跡などと連携できます。

Nubiia が構築・保守しています — ビジネス向けの自動化と AI インテグレーション（MCP、Holded、Pipedrive など）。貴社でも同様のものをお求めですか？ nubiia.es までお問い合わせください。

特長

この MCP サーバーでは、サポート対象のすべてのモジュールにおいて Holded API v2 を利用できます。

• 書類（16 個のツール）：請求書、見積書、クレジットノートなどの作成、一覧表示、更新、削除ができます。支払い、送信、PDF の取得、商品の発送なども可能です。
• 連絡先（7 個のツール）：添付ファイルを含め、顧客や仕入先を管理します。
• 製品（9 個のツール）：画像や在庫を含め、製品を包括的に管理します。
• 財務（3 個のツール）：旧式の財務アカウントを管理します。
• 財務 v2（15 個のツール）：銀行口座、銀行の入出金、現金の入出金、請求予測、照合を管理します。
• 経費勘定（5 個のツール）：経費勘定のカテゴリを管理します。
• 採番シリーズ（4 個のツール）：書類の採番を設定します。
• 販売チャネル（5 個のツール）：販売チャネルを管理します。
• 倉庫（6 個のツール）：倉庫を管理します。
• 支払い（5 個のツール）：支払い方法を設定します。
• 税金（1 個のツール）：利用可能な税金を取得します。
• 連絡先グループ（5 個のツール）：連絡先をグループに整理します。
• 送金（2 個のツール）：送金データにアクセスします。
• サービス（5 個のツール）：サービスを管理します。
• 時間追跡（3 個のツール）：時間追跡の記録とプロジェクトの作業時間を一覧表示します（読み取りと書き込み）。
• 会計（2 個のツール、読み取り専用）：勘定科目表と日次元帳を取得します。
• 元帳（4 個のツール）：会計／元帳の記録を一覧表示・作成します。
• チーム／人事（22 個のツール）：従業員、給与記録、従業員の時間記録、出退勤を管理します。

合計：119 個のツール — 有効な v2 キーが設定されると、すべて無条件で登録されます。

インストール

前提条件

• Node.js 22.14 以降
• API アクセスが有効な Holded アカウント
• Holded API v2 キー（pat_… または sk_live_…） — Holded → Settings → API で生成します

npm からインストール

npm install -g @nubiia/mcp-holded

ソースからインストール

git clone https://github.com/nubiia-dev/mcp-holded.git
cd mcp-holded
npm install
npm run build

設定

環境変数

すべてのツールは Holded API v2 を呼び出します（Bearer 認証、カーソルページネーション）。必要な v2 キーは 1 つです。

# Recommended — primary key name
export HOLDED_API_KEY=pat_your_v2_key_here

# Alternative — accepted as an alias; wins over HOLDED_API_KEY if both are set
export HOLDED_API_KEY_V2=sk_live_your_v2_key_here

キーは Holded → Settings → API で生成します。キーは pat_ または sk_live_ で始まる必要があります。403 応答は、キーに必要なスコープがないことを示します。

マルチテナント環境では、テナントごとに同じ設定を行います。

export TENANT_1_NAME=company-a
export TENANT_1_API_KEY=pat_key_for_company_a
export TENANT_2_NAME=company-b
export TENANT_2_API_KEY=sk_live_key_for_company_b

TENANT_N_API_KEY_V2 は TENANT_N_API_KEY のエイリアスとして使用できます（両方が設定されている場合は、こちらが優先されます）。

Claude Desktop の設定

Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

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

ソースからインストールした場合は、次のように設定します。

{
  "mcpServers": {
    "holded": {
      "command": "node",
      "args": ["/path/to/mcp-holded/dist/index.js"],
      "env": {
        "HOLDED_API_KEY": "pat_your_v2_key_here"
      }
    }
  }
}

1.x からの移行

API キー

サーバーは現在、Holded API v2 のみを呼び出します。1.x の API キー（abc123… のような通常の 16 進数文字列）は使用できなくなりました。Holded → Settings → API で v2 キーを生成してください。キーは pat_ または sk_live_ で始まります。

HOLDED_API_KEY（またはその別名 HOLDED_API_KEY_V2）に設定してください。1.x で HR／Ledger／Treasury ツールをオプトインするために使われていた別個の HOLDED_API_KEY_V2 変数は不要になりました。119 個すべてのツールが常に登録されます。

ページネーション

リストツールのページネーションは、ページ番号ベースからカーソルベースに変更されました。

1.x の引数	2.x の引数	備考
page	(削除)	サーバーはオフセットページを受け付けなくなりました
pageSize	limit	サーバー側でページネーションされます。ページサイズの制御には limit を使用してください
(なし)	cursor	前回のレスポンスの nextCursor を渡します

レスポンスの形式は次のエンベロープに変更されました。

{
  "items": [...],
  "nextCursor": "opaque-string-or-null",
  "hasMore": true
}

hasMore が false になるまで、nextCursor を cursor として渡して繰り返してください。

レスポンス形式

• フィールド名はすべて snake_case です（例：contact_id、created_at）。
• 金額は小数点にカンマを使った文字列です（例："1.234,56"）。計算を行う前に、ロケールに対応した数値パーサーで解析してください。

削除または変更された操作

操作	1.x の動作	2.x の動作
purchaserefund の list／get／update／delete／pay	対応	削除 — /purchases/refund からの作成のみ可能
update_document の追跡	すべてのドキュメントタイプ	salesorder と waybill のみ
出荷操作	すべてのドキュメントタイプ	salesorder と purchaseorder のみ
試験的な銀行機能（reconcile_bank_transaction）	環境変数フラグによるオプトイン	削除 — reconcile_bank_movement（treasury v2）を使用してください
get_daily_ledger の日付	Unix タイムスタンプ（starttmp／endtmp）	ISO 8601 形式の文字列（start_date／end_date）。利便性のため、従来の Unix 引数も引き続き受け付けます
get_taxes	ページネーションあり	1 回の呼び出しですべての税金を返します（ページネーション引数なし）
update_product_stock	倉庫は任意	warehouse_id が必須になりました
リストツールのフィールド射影	デフォルトのフィールドセットを縮小	v2 の完全なペイロードを返します。絞り込みには fields 引数を使用してください

連絡先の添付ファイル

添付ファイルは、添付ファイル ID ではなくファイル名で取得されるようになりました。list_contact_attachments が返す filename フィールドを使って、get_contact_attachment を呼び出してください。

使用例

設定が完了すると、Claude に次のように依頼できます。

ドキュメント

• 「Holded のすべての請求書を一覧表示して」
• 「商品 2 点を含む、クライアント X 宛ての請求書を作成して」
• 「請求書 #123 をメールでクライアントに送って」
• 「請求書 #456 の PDF を取得して」
• 「請求書 #789 を支払い済みにして」

連絡先

• 「Holded のすべてのクライアントを一覧表示して」
• 「Acme Corp という名前の新しいクライアントを作成して」
• 「連絡先 #123 のメールアドレスを更新して」

製品

• 「すべての製品を表示して」
• 「価格 50 EUR の Widget という新しい製品を作成して」
• 「倉庫 W1 に製品 #123 の在庫を 10 個追加して」

HR と給与

• 「すべての従業員を一覧表示して」
• 「従業員 #456 の出勤を記録して」
• 「従業員 #789 の 2025 年 6 月の給与記録を取得して」

レポート

• 「すべての税金を取得して」
• 「すべての財務部門の銀行口座を一覧表示して」
• 「2025 年 1 月の日次元帳を表示して」
• 「勘定科目表を取得して」

ドキュメントタイプ

API は次のドキュメントタイプに対応しています。

タイプ	説明
invoice	売上請求書
salesreceipt	売上領収書
creditnote	クレジットノート（返金）
receiptnote	領収書
estimate	見積もり
salesorder	販売注文
waybill	梱包明細書
proform	プロフォーマ請求書
purchase	購入
purchaserefund	購入の返金（v2 では作成のみ）
purchaseorder	発注書

API リファレンス

ベース URL

https://api.holded.com/api/

サーバーは各ツールを適切な v2 サブパス（例：/invoicing/v2/、/team/v2/、/accounting/v2/）にルーティングします。

認証

すべてのリクエストは、v2 キーを使った Bearer 認証を使用します。

Authorization: Bearer pat_your_v2_key_here

ページネーション

リストエンドポイントでは、limit および cursor 引数を使用したカーソルベースのページネーションを利用します（1.x からの移行を参照）。

開発

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

書き込みの安全性

作成・更新・削除ツールは、Holded の実データを変更します。サーバーは、誤って大量のデータを変更することを防ぐため、ツールごとにレート制限を適用します（破壊的な操作には、より厳しい制限が適用されます）。破壊的な操作はデフォルトで毎分 10 リクエスト、更新操作は毎分 30 リクエストに制限されます。

プライバシーポリシー

データの収集：この MCP サーバーの動作には、Holded API キーが必要です。API キーはローカルの環境変数（HOLDED_API_KEY）から読み込まれ、このサーバーに保存されることはありません。AI アシスタントと Holded API 間の通信を可能にするため、すべての API リクエストとレスポンスはリアルタイムで中継されます。

データの使用と共有：API キーと、このサーバーを通じて処理されるすべてのデータは、お客様に代わって Holded API とやり取りする目的にのみ使用されます。サーバーは中継プロキシとして動作し、データの保存、ログ記録、保持は行いません。Holded API キーとデータは、Holded の公式 API エンドポイント（api.holded.com）にのみ送信されます。Holded 以外の第三者とデータを共有することはありません。

お客様のセキュリティ：セキュリティのベストプラクティスに従うことをおすすめします。API キーは環境変数に保存し（バージョン管理にコミットしないでください）、常に最新バージョンに更新し、AI アシスタントでこの MCP サーバーに付与されている権限を確認してください。詳しくはプライバシーポリシー全文をご覧ください。

サポート

ご質問、不具合の報告、機能のリクエストについては、以下をご利用ください。

• GitHub Issues：問題を報告
• メール：[email protected]
• ドキュメント：Holded API ドキュメント

Nubiia について

この MCP サーバーは、Nubiia が開発・保守しています。

Nubiia は、企業のプロセスの自動化や、AI を活用したツールの統合を支援しています。カスタム MCP サーバー、Holded、Pipedrive、その他の ERP／CRM との統合、そしてビジネスデータを Claude などのアシスタントにつなぐエージェントを提供しています。この @nubiia/mcp-holded は、私たちの取り組みを示すオープンソースの一例です。

👉 ビジネス向けの AI 統合や自動化をご希望ですか？ nubiia.es · ✉️ [email protected]

ライセンス

MIT — 詳細は LICENSE ファイルをご覧ください。

作者

Nubiia が開発 — nubiia.es · [email protected]

メンテナー：Samuel Fraga — GitHub · LinkedIn

リンク

• Nubiia — AI による自動化と統合
• Holded API ドキュメント
• MCP 仕様
• プライバシーポリシー