mcp-quipu

面向 Quipu API 的 MCP 服务器：为西班牙的个体经营者和小企业提供开票、支出、联系人和会计功能。

它可以让 Claude 这样的助手用自然语言查询和操作你的 Quipu 账户：“这个季度我开了多少发票？”、“请为这个客户创建九月份的发票”、“给我最近一张发票的 PDF”。

由 Nubiia 构建，是 mcp-holded 的兄弟项目。

状态：alpha（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 key。 与 Holded 不同，Quipu 签发的 token 会过期。客户端将它们缓存在内存中，在到期前 60 秒续期，并在并发调用之间共享同一个请求。遇到 401 时会使 token 失效并重试。

扁平化的 JSON:API。 Quipu 返回 { data: { id, attributes: {…} } }。工具将响应扁平化为 { id, …attributes }，因为模型对扁平对象的推理效果要好得多，而且还能节省包装 token。

写操作比读操作受到更多限制。 出错时创建的一张发票并不是数据库中的一行：它是一份具有法律效力的文件。写操作有更严格的配额，破坏性操作会用 destructiveHint 标注。

税务计算在代码中完成，而非由模型完成。 Quipu 不公开任何税务申报表端点（130、303、111），因此这些数字必须从发票和支出中推导得出。get_tax_summary 遍历这两个资源的所有页面，四舍五入到分后求和，并返回已计算好的余额。让模型逐 token 去累加一长串金额，是得到错误税务数字的可靠方法。

金额以文本形式返回，且命名不够直观。 基础金额为 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

• 通过 GET /users/{id} 自动解析 owner_slug

许可证

MIT