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

Optional Environment Variables

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)

Account Groups / Inventory Categories (3 tools)

Customers (5 tools)

Invoices (10 tools)

Batch Invoices (1 tool)

Quotations (5 tools)

Credit Notes (4 tools)

Vouchers / Cash Receipts (3 tools)

Purchase Support Documents (5 tools)

Purchases (5 tools)

Payment Receipts / Disbursements (5 tools)

Journals / Accounting Entries (3 tools)

Webhooks (4 tools)

Catalogs (13 tools + account groups above)

Reports (3 tools)

Document Types Reference

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