mcp-quipu

mcp-quipu

Quipu API 用の MCP サーバーです。スペインの自営業者や中小企業向けに、請求書、経費、連絡先、会計を管理します。

Claude などのアシスタントが、自然言語で Quipu アカウントを参照、操作できます。「今四半期の請求額はいくらですか？」、「この顧客の9月分の請求書を作成してください」、「直近の請求書の PDF をください」。

Nubiia が開発しました。mcp-holded の姉妹プロジェクトです。

ステータス：安定版（v1.0.0）。 連絡先、請求書、経費、税務集計に関する18個のツールを提供します。API のその他のリソースは docs/api-map.md にマッピングされていますが、まだ公開されていません。

インストール

npm install -g @nubiia/mcp-quipu

設定

Quipu の API 認証情報（設定 → API）とアカウントの slug が必要です。slug は Quipu の URL の最初のセグメントです。https://getquipu.com/<slug>/…

{
  "mcpServers": {
    "quipu": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-quipu"],
      "env": {
        "QUIPU_CLIENT_ID": "tu_client_id",
        "QUIPU_CLIENT_SECRET": "tu_client_secret",
        "QUIPU_OWNER_SLUG": "tu_slug"
      }
    }
  }
}

利用可能なツール

連絡先

ツール	説明
list_contacts	連絡先を一覧表示します。名前での絞り込みとページネーションに対応しています
get_contact	連絡先の詳細を取得します
create_contact	連絡先を作成します（name が必要です。請求書の発行には NIF/CIF が必須です）
update_contact	指定したフィールドのみを更新します
delete_contact	連絡先を削除します

請求書

ツール	説明
list_invoices	発行済みの請求書を一覧表示します。期間を指定して絞り込めます
get_invoice	請求書の詳細を取得します
create_invoice	明細、IVA、IRPF を含む請求書を発行します
update_invoice	請求書を更新します
delete_invoice	請求書を削除します
get_invoice_download_url	PDF をダウンロードするための一時 URL を取得します

経費と追加収入

ツール	説明
list_additional_incomes	経費と収入を一覧表示します。期間を指定して絞り込めます
get_additional_income	エントリーの詳細を取得します
create_additional_income	仕入先の請求書または控除対象の経費を登録します
update_additional_income	エントリーを更新します
delete_additional_income	エントリーを削除します
get_additional_income_download_url	PDF の一時 URL を取得します

税務

ツール	説明
get_tax_summary	四半期または指定期間の売上 IVA、仕入 IVA、差引残高、源泉徴収額を取得します

設計上の注意点

API キーではなく OAuth2。 Holded とは異なり、Quipu が発行するトークンには有効期限があります。クライアントはトークンをメモリ内にキャッシュし、60 秒の余裕をもって更新するとともに、同時に発生した呼び出しでは更新リクエストを 1 件にまとめます。401 が返された場合はトークンを無効化して再試行します。

JSON:API をフラット化。 Quipu は { data: { id, attributes: {…} } } を返します。ツールはレスポンスを { id, …attributes } にフラット化します。モデルはフラットなオブジェクトのほうがはるかに推論しやすく、ラッパーに使うトークンも節約できるためです。

書き込みの制限は読み取りより厳しくしています。 誤って作成した請求書は、データベースの 1 行ではなく、法的効力を持つ書類です。書き込み操作にはより厳しい上限を設け、破壊的な操作には destructiveHint を付けています。

税額の計算はモデルではなくコードで行います。 Quipu には税務申告モデル（130、303、111）のエンドポイントがないため、請求書と経費から数値を算出する必要があります。get_tax_summary は両方のリソースの全ページを走査し、セント単位で丸めて合計し、計算済みの残高を返します。長い金額リストをモデルにトークン単位で合計させると、税額を誤る可能性が高くなります。

金額はテキストで返され、項目名も分かりにくいものです。 税抜きの基本金額は total_amount_without_taxes、税額は vat_amount です。total や subtotal はありません。合計処理では小数点としてコンマを受け付け、空の値を無視します。また、解析できない値は伝播して予期しない NaN になるのではなく、除外したうえでレスポンスに警告を含めます。

請求書の削除について。 スペインの規制では、すでに採番された請求書を削除するのではなく、訂正請求書を発行して修正する必要があります。API で可能なため delete_invoice は存在しますが、ツールの説明で注意を促し、モデルが安易に提案しないようにしています。

開発

npm install
npm run build
npm test
npm run lint

ロードマップ

• simplified_invoices — レシートと簡易請求書（7 ops）
• paysheets — 給与明細（5 ops）
• numbering_series、accounting_categories、accounting_subcategories
• attachments と book_entries
• GET /users/{id} を使った owner_slug の自動解決

ライセンス

MIT