Siigo MCP Server

A Model Context Protocol (MCP) server that provides full integration with the Siigo API, enabling access to Colombian accounting software features including products, customers, invoices, quotations, purchases, credit notes, vouchers, payment receipts, journals, webhooks, and more.

v3.2.0 - Split tool modules for maintainability, 75 tools, purchase support documents, updated cash receipt support, MCP SDK v1.29, Zod schemas, improved MCP error propagation, and complete TypeScript type safety.

Features

This MCP server provides access to all Siigo API endpoints:

Core Resources

• Products: Full CRUD for products, services, consumer goods, and Combo products with components
• Customers: Manage customers, suppliers, and third parties
• Invoices: Sales invoices with electronic invoicing, healthcare sector, batch creation, annulment, PDF, XML, and DIAN error queries
• Quotations: Full CRUD for quotations (cotizaciones) -- NEW in v3
• Purchase Support Documents: Full CRUD for documentos soporte (/purchase-support-documents)
• Purchases: Purchase invoices and expenses
• Credit Notes: Create and query credit notes with PDF support and healthcare sector fields
• Vouchers: Cash receipts (recibos de caja), including debt payments, advance payments, and miscellaneous income
• Payment Receipts: Payment receipts / disbursements (recibos de pago / comprobantes de egreso) - full CRUD
• Journals: Accounting journal entries (comprobantes contables)
• Webhooks: Subscribe to and manage webhook events -- NEW in v3

Inventory Management

• Account Groups: Create and edit inventory categories -- NEW in v3

Catalogs

• Document types (FV, RC, NC, FC, CC, RP, C, DS)
• Taxes, payment types, cost centers
• Users/sellers, warehouses, price lists
• Account groups, cities, ID types
• Fiscal responsibilities, fixed assets, expenses, miscellaneous income concepts

Reports

• Trial balance reports (general and by third party)
• Accounts payable reports

Installation

Option 1: NPX (Recommended - No Installation Required)

npx @jdlar/siigo-mcp

Option 2: Global Installation

npm install -g @jdlar/siigo-mcp
siigo-mcp

Option 3: Local Development / Building from Source

git clone https://github.com/jdlar1/siigo-mcp.git
cd siigo-mcp
npm install
npm run build
cp .env.example .env
# Edit .env with your Siigo credentials

Configuration

Required Environment Variables

Variable	Description
SIIGO_USERNAME	Your Siigo API username
SIIGO_ACCESS_KEY	Your Siigo API access key
SIIGO_PARTNER_ID	Partner ID for API identification (3-100 alphanumeric chars, no spaces)

Optional Environment Variables

Variable	Default	Description
SIIGO_BASE_URL	https://api.siigo.com	API base URL

Getting Siigo API Credentials

1. Sign up for a Siigo account at siigo.com
2. Access the API section in your Siigo dashboard
3. Generate your API credentials (username and access key)
4. For testing, use the sandbox environment

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "siigo": {
      "command": "npx",
      "args": ["@jdlar/siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "your_username",
        "SIIGO_ACCESS_KEY": "your_access_key",
        "SIIGO_PARTNER_ID": "your_app_name"
      }
    }
  }
}

Available Tools (68 total)

Products (6 tools)

Tool	Description	Annotations
siigo_get_products	List products with pagination	read-only
siigo_get_product	Get a product by ID	read-only
siigo_create_product	Create product (supports Combo type with components)
siigo_update_product	Update a product
siigo_delete_product	Delete a product	destructive
siigo_search_products	Search by code, name, or reference (partial match)	read-only

Account Groups / Inventory Categories (3 tools)

Tool	Description	Annotations
siigo_get_account_groups	List inventory categories	read-only
siigo_create_account_group	Create inventory category
siigo_update_account_group	Update inventory category

Customers (5 tools)

Tool	Description	Annotations
siigo_get_customers	List customers	read-only
siigo_get_customer	Get a customer by ID	read-only
siigo_create_customer	Create a customer/third party
siigo_update_customer	Update a customer
siigo_search_customers	Search by identification, name, or type	read-only

Invoices (10 tools)

Tool	Description	Annotations
siigo_get_invoices	List invoices with date filters	read-only
siigo_get_invoice	Get an invoice by ID	read-only
siigo_create_invoice	Create invoice (supports healthcare and transport sectors)
siigo_update_invoice	Update an invoice
siigo_delete_invoice	Delete an invoice	destructive
siigo_annul_invoice	Annul (void) an invoice	destructive
siigo_get_invoice_pdf	Get invoice PDF (base64)	read-only
siigo_get_invoice_xml	Get invoice electronic XML (base64)	read-only
siigo_get_invoice_stamp_errors	Get DIAN rejection errors	read-only
siigo_send_invoice_email	Send invoice by email (up to 5 addresses)

Batch Invoices (1 tool)

Tool	Description	Annotations
siigo_create_invoice_batch	Create invoices in batch (async with webhook notification)

Quotations (5 tools)

Tool	Description	Annotations
siigo_get_quotations	List quotations with date filters	read-only
siigo_get_quotation	Get a quotation by ID	read-only
siigo_create_quotation	Create a quotation (document type C)
siigo_update_quotation	Update a quotation
siigo_delete_quotation	Delete a quotation	destructive

Credit Notes (4 tools)

Tool	Description	Annotations
siigo_get_credit_notes	List credit notes	read-only
siigo_get_credit_note	Get a credit note by ID	read-only
siigo_create_credit_note	Create credit note (supports healthcare sector, external invoice refs)
siigo_get_credit_note_pdf	Get credit note PDF (base64)	read-only

Vouchers / Cash Receipts (3 tools)

Tool	Description	Annotations
siigo_get_vouchers	List cash receipts (recibos de caja)	read-only
siigo_get_voucher	Get a cash receipt by ID	read-only
siigo_create_voucher	Create cash receipt (DebtPayment, AdvancePayment, MiscIncome)

Purchase Support Documents (5 tools)

Tool	Description	Annotations
siigo_get_purchase_support_documents	List purchase support documents	read-only
siigo_get_purchase_support_document	Get a purchase support document by ID	read-only
siigo_create_purchase_support_document	Create purchase support document (document type DS)
siigo_update_purchase_support_document	Update a purchase support document
siigo_delete_purchase_support_document	Delete a purchase support document	destructive

Purchases (5 tools)

Tool	Description	Annotations
siigo_get_purchases	List purchase invoices	read-only
siigo_get_purchase	Get a purchase by ID	read-only
siigo_create_purchase	Create purchase (use FC type with document_support for Documento Soporte)
siigo_update_purchase	Update a purchase
siigo_delete_purchase	Delete a purchase	destructive

Payment Receipts / Disbursements (5 tools)

Tool	Description	Annotations
siigo_get_payment_receipts	List payment receipts (recibos de pago / comprobantes de egreso)	read-only
siigo_get_payment_receipt	Get a payment receipt by ID	read-only
siigo_create_payment_receipt	Create payment receipt (DebtPayment, AdvancePayment, Advanced)
siigo_update_payment_receipt	Update a payment receipt
siigo_delete_payment_receipt	Delete a payment receipt	destructive

Journals / Accounting Entries (3 tools)

Tool	Description	Annotations
siigo_get_journals	List accounting journals (comprobantes contables)	read-only
siigo_get_journal	Get a journal by ID	read-only
siigo_create_journal	Create journal entry (debits must equal credits)

Webhooks (4 tools)

Tool	Description	Annotations
siigo_get_webhooks	List webhook subscriptions	read-only
siigo_create_webhook	Subscribe to a webhook event
siigo_update_webhook	Update a webhook subscription
siigo_delete_webhook	Delete a webhook subscription	destructive

Catalogs (13 tools + account groups above)

Tool	Description
siigo_get_document_types	Document types (FV, RC, NC, FC, CC, RP, C, DS)
siigo_get_taxes	Taxes (IVA, Retefuente, ReteIVA, ReteICA, etc.)
siigo_get_payment_types	Payment methods
siigo_get_cost_centers	Cost centers
siigo_get_users	Users/sellers
siigo_get_warehouses	Warehouses
siigo_get_price_lists	Price lists (up to 12)
siigo_get_cities	Colombian cities
siigo_get_expenses	Expenses for cash receipt adjustments
siigo_get_misc_income	Miscellaneous income concepts for cash receipts
siigo_get_id_types	Identification types
siigo_get_fiscal_responsibilities	Fiscal responsibilities
siigo_get_fixed_assets	Fixed assets

Reports (3 tools)

Tool	Description
siigo_get_trial_balance	Trial balance report (Excel)
siigo_get_trial_balance_by_third	Trial balance by third party (Excel)
siigo_get_accounts_payable	Accounts payable report

Document Types Reference

Code	Spanish Name	English Name	MCP Support
FV	Factura de Venta	Sales Invoice	Full CRUD + PDF/XML/Email/Batch/Annul
RC	Recibo de Caja	Cash Receipt	Create + Query
NC	Nota Credito	Credit Note	Create + Query + PDF
FC	Factura de Compra	Purchase Invoice	Full CRUD
CC	Comprobante Contable	Accounting Journal	Create + Query
RP	Recibo de Pago/Egreso	Payment Receipt	Full CRUD
C	Cotizacion	Quotation	Full CRUD

Example Usage

Create a Quotation

{
  "name": "siigo_create_quotation",
  "arguments": {
    "quotation": {
      "document": { "id": 12345 },
      "date": "2026-02-13",
      "customer": { "identification": "13832081", "branch_office": 0 },
      "seller": 629,
      "items": [{
        "code": "PROD001",
        "quantity": 5,
        "price": 50000,
        "taxes": [{ "id": 13156 }]
      }]
    }
  }
}

Create a Combo Product

{
  "name": "siigo_create_product",
  "arguments": {
    "product": {
      "code": "COMBO-001",
      "name": "Kit de oficina",
      "account_group": 1253,
      "type": "Combo",
      "components": [
        { "code": "PROD-001", "quantity": 2 },
        { "code": "PROD-002", "quantity": 1 }
      ]
    }
  }
}

Create a Healthcare Invoice

{
  "name": "siigo_create_invoice",
  "arguments": {
    "invoice": {
      "document": { "id": 24446 },
      "date": "2026-02-13",
      "customer": { "identification": "13832081" },
      "seller": 629,
      "items": [{ "code": "SRV001", "quantity": 1, "price": 150000 }],
      "payments": [{ "id": 5636, "value": 150000 }],
      "healthcare_company": {
        "operation_type": "SS-CUFE",
        "period_start": "2026-01-01",
        "period_end": "2026-01-31"
      }
    }
  }
}

Create Batch Invoices

{
  "name": "siigo_create_invoice_batch",
  "arguments": {
    "notification_url": "https://myapp.com/webhooks/siigo-batch",
    "invoices": [
      {
        "idempotency_key": "INV202602001",
        "document": { "id": 24446 },
        "date": "2026-02-13",
        "customer": { "identification": "13832081" },
        "seller": 629,
        "items": [{ "code": "PROD001", "quantity": 1, "price": 50000 }],
        "payments": [{ "id": 5636, "value": 50000 }]
      }
    ]
  }
}

API Rate Limits

• Production: 100 requests per minute per company
• Sandbox: 10 requests per minute

The server uses a 120-second HTTP timeout as recommended by Siigo for long-running operations.

Error Handling

The server handles Siigo API errors and returns structured error responses with error codes, messages, and details. See the Siigo API docs for a full list of error codes.

Development

Project Structure

siigo-mcp/
├── src/
│   ├── index.ts          # MCP server - tool registration with Zod schemas
│   ├── siigo-client.ts   # HTTP client for all Siigo API endpoints
│   └── types.ts          # Full TypeScript interfaces for all document types
├── dist/                 # Compiled output (ESM)
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Building

npm run build

Running for Development

npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run build to verify
5. Submit a pull request

License

MIT License

Support

• Siigo API: Contact soporteapi@siigo.com
• This MCP server: Create an issue

Links

• Siigo API Documentation
• Model Context Protocol
• MCP TypeScript SDK
• Siigo Official Website