mcp-quipu

MCP-сервер для API Quipu: выставление счетов, расходы, контакты и бухгалтерия для самозанятых и малых предприятий в Испании.

Позволяет такому ассистенту, как Claude, запрашивать и управлять вашим аккаунтом Quipu на естественном языке: «Сколько я выставил счетов за этот квартал?», «Создайте мне счет за сентябрь для этого клиента», «Дайте мне 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

Настройка

Вам нужны учетные данные API Quipu (Настройки → API) и slug вашего аккаунта, который является первым сегментом ваших URL-адресов Quipu: 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 секунд и разделяет один запрос между параллельными вызовами. При получении 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

• Автоматическое определение owner_slug через GET /users/{id}

Лицензия

MIT