mcp-quipu

スペインの個人事業主と小規模企業向けに、請求、経費、取引先、会計を扱うQuipu API用のMCPサーバーです。

Claudeのようなアシスタントが自然言語でQuipuアカウントを照会・操作できるようにします: 「今四半期の請求額はいくら?」、「この顧客への9月の請求書を作成して」、「最後の請求書のPDFをください」。

Nubiiaによって構築されました。mcp-holdedの兄弟プロジェクトです。

ステータス: アルファ (v0.1.0)。 取引先、請求書、経費、税務集計に関する18のツールを備えています。APIのその他のリソースは docs/api-map.md にマッピングされていますが、まだ公開されていません。

インストール

npm install -g @nubiia/mcp-quipu

Related MCP server: QuickBooks Online MCP Server

設定

Quipu APIの認証情報（設定 → API）と、アカウントの 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"
      }
    }
  }
}

利用可能なツール

取引先

請求書

追加の支出と収入

税務

設計上の注意

OAuth2、APIキーではない。 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 を伝播させることはありません。

請求書の削除について。 スペインの法令では、番号が付与された請求書を削除するのではなく、修正請求書によって訂正することが求められます。delete_invoice はAPIが許可しているために存在しますが、ツールの説明にはその旨が記載されており、モデルが軽々しく削除を提案しないようになっています。

開発

npm install
npm run build
npm test
npm run lint

ロードマップ

• simplified_invoices — レシートと簡易請求書（7操作）

• paysheets — 給与（5操作）

• numbering_series、accounting_categories、accounting_subcategories

• attachments と book_entries

• owner_slug の自動解決（GET /users/{id} 経由）

ライセンス

MIT