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가 필요합니다. 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초의 여유를 두고 갱신하며, 동시 호출 간에 단일 요청을 공유합니다. 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