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，也就是 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、余额和预扣税

设计说明

OAuth2，而非 API key。 与 Holded 不同，Quipu 发放的令牌会过期。客户端会在内存中缓存令牌，提前 60 秒续期，并让并发调用共用同一个请求。遇到 401 时，会使令牌失效并重试。

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

写入操作的限制比读取操作更严格。 错误创建的发票不是数据库中的一行记录，而是一份具有法律效力的文件。写入操作的额度限制更严格，破坏性操作则标注了 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
• 通过 GET /users/{id} 自动解析 owner_slug

许可证

MIT