Siigo MCP Server
Provides full MCP integration with the Siigo Colombian accounting API, enabling CRUD and operations across accounting resources via task-oriented and legacy tools.
Products: Full CRUD, search, combo products with components
Customers: Full CRUD, search, manage suppliers/third parties
Invoices: Create, update, delete, annul, list, get by ID, PDF, XML, email, batch creation, healthcare/transport support
Quotations: Full CRUD
Credit Notes: Create, query, PDF, healthcare fields
Vouchers (Cash Receipts): Create and query (debt payment, advance payment, misc income)
Purchases: Full CRUD
Payment Receipts (Disbursements): Full CRUD
Journals (Accounting Entries): Create and query
Webhooks: Subscribe, update, delete webhook events
Catalogs: Document types, taxes, payment types, cost centers, users, warehouses, price lists, account groups, fixed assets, expenses, misc income
Reports: Trial balance, trial balance by third party, accounts payable
Inventory: Account groups (categories) CRUD
Additional Catalogs (via schema): cities, ID types, fiscal responsibilities
Task-oriented tools: search, read/write/destructive executors, operation discovery, on-demand schemas
Used for managing environment variables and configuration settings for Siigo API credentials
Used for package management and dependency installation in the Node.js-based MCP server implementation
Used as the programming language for implementing the MCP server with type safety
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Siigo MCP Server show me all invoices from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
v6.0.1 — Eight task-oriented tools with on-demand access to all 71 operations. Prepare invoices, quotations, purchases, and cash receipts; create all eight document kinds through one validated tool. Search and inspect records, with separate read, write, and destructive executors. Requires Node 24 or newer. See the v6 migration guide. This patch fixes customer search when Siigo returns an address without city codes.
Features
This MCP server covers the current documented Siigo Colombia API surface listed in the coverage matrix. Source conflicts are resolved using the published source-of-truth policy.
It is intentionally broader than Siigo's official MCP, whose current documentation lists read operations for products, create/read/update for customers, and create/read for sales invoices. This server covers 15 Siigo resource families through 71 operations, including accounting, purchasing, catalogs, reports, webhooks, and the extended invoice lifecycle.
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)
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
Inventory Management
Account Groups: Create and edit inventory categories
Catalogs
Document types (FV, RC, NC, FC, CC, RP, C, DS)
Taxes, payment types, cost centers
Users/sellers, warehouses, price lists
Account groups, fixed assets, expenses, miscellaneous income concepts
Reports
Trial balance reports (general and by third party)
Accounts payable reports
Related MCP server: Siigo MCP Server
Installation
Requires Node 24 LTS. For local development, run nvm use before installing dependencies.
Option 1: NPX (Recommended - No Installation Required)
npx @jdlar/siigo-mcpOption 2: Global Installation
npm install -g @jdlar/siigo-mcp
siigo-mcpOption 3: Local Development / Building from Source
git clone https://github.com/jdlar1/siigo-mcp.git
cd siigo-mcp
pnpm install
pnpm build
cp .env.example .env
# Edit .env with your Siigo credentialsConfiguration
Required Environment Variables
Variable | Description |
| Your Siigo API username |
| Your Siigo API access key |
| Partner ID for API identification (3-100 alphanumeric chars, no spaces) |
Optional Environment Variables
Variable | Default | Description |
|
| API base URL |
|
| Client-side requests per rolling minute (1-100); set |
|
| Task-oriented tools; set |
|
| MCP transport: |
|
| HTTP bind address |
|
| HTTP listening port |
| — | Bearer token for HTTP requests; required when binding outside loopback |
| — | Optional comma-separated HTTP Host allowlist |
Siigo documents a limit of 100 requests per minute in production and 10 requests per minute for test companies. The client defaults to 100; set SIIGO_REQUESTS_PER_MINUTE=10 when using a test company. Values outside 1-100 are rejected at startup.
Getting Siigo API Credentials
Sign up for a Siigo account at siigo.com
Access the API section in your Siigo dashboard
Generate your API credentials (username and access key)
For testing, use the sandbox environment
MCP Client Configuration
Stateless Streamable HTTP
The default transport remains stdio. To run a stateless HTTP endpoint locally:
MCP_TRANSPORT=http pnpm startThe endpoint is available at http://127.0.0.1:3000/mcp. The SDK serves modern MCP requests and legacy stateless clients. Requests use separate MCP server instances with a shared, client-scoped lazy operation registry. Legacy requests retain JSON responses without MCP session IDs; modern requests use JSON or SSE according to protocol needs.
For a network-accessible deployment, set an explicit bearer token:
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
MCP_AUTH_TOKEN=replace_with_a_long_random_token \
pnpm startClients must send Authorization: Bearer <token>. Terminate TLS at a trusted reverse proxy or hosting platform; do not expose the endpoint over plaintext HTTP.
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": "yourappname"
}
}
}
}TypeScript library API
The package exposes a side-effect-free library entrypoint as well as the executable:
import { SiigoClient, type SiigoInvoiceInput } from '@jdlar/siigo-mcp';
import { invoiceSchemas } from '@jdlar/siigo-mcp/schemas';
const client = new SiigoClient({
username: process.env.SIIGO_USERNAME!,
accessKey: process.env.SIIGO_ACCESS_KEY!,
partnerId: process.env.SIIGO_PARTNER_ID!,
baseUrl: 'https://api.siigo.com',
});
declare const input: unknown;
const invoice: SiigoInvoiceInput = invoiceSchemas.invoiceInputSchema.parse(input);
const created = await client.createInvoice(invoice, { idempotencyKey: 'Invoice2026082601' });Supported subpath exports are client, contracts, server, legacy-server, http, results, schemas, types, and version.
Task-oriented tools
The default catalog exposes eight tools: search, record retrieval, document preparation and creation, operation discovery, and separate read/write/destructive executors. Catalogs, reports, advanced operation schemas, and document workflow schemas are retrieved on demand. Secondary handlers load by domain.
See compact tools and migration for the complete initial catalog, examples, compatibility options, and validation boundaries.
Legacy tools and discoverable operations
The following names are directly callable with SIIGO_TOOL_PROFILE=legacy.
In the default compact profile, use siigo_discover_operations and the returned
executor for these operations. Prefer siigo_create_document for document creation.
Products (6 tools)
Tool | Description | Annotations |
| List products with pagination | read-only |
| Get a product by ID | read-only |
| Create product (supports Combo type with components) | |
| Update a product | |
| Delete a product | destructive |
| Search by code, name, or reference (partial match) | read-only |
Account Groups / Inventory Categories (3 tools)
Tool | Description | Annotations |
| List inventory categories | read-only |
| Create inventory category | |
| Update inventory category |
Customers (5 tools)
Tool | Description | Annotations |
| List customers | read-only |
| Get a customer by ID | read-only |
| Create a customer/third party | |
| Update a customer | |
| Search by identification, name, or type | read-only |
Invoices (10 tools)
Tool | Description | Annotations |
| List invoices with date filters | read-only |
| Get an invoice by ID | read-only |
| Create invoice (supports healthcare and transport sectors) | |
| Update an invoice | |
| Delete an invoice | destructive |
| Annul (void) an invoice | destructive |
| Get invoice PDF (base64) | read-only |
| Get invoice electronic XML (base64) | read-only |
| Get DIAN rejection errors | read-only |
| Send invoice by email (up to 5 addresses) |
Batch Invoices (1 tool)
Tool | Description | Annotations |
| Create invoices in batch (async with webhook notification) |
Quotations (5 tools)
Tool | Description | Annotations |
| List quotations with date filters | read-only |
| Get a quotation by ID | read-only |
| Create a quotation (document type C) | |
| Update a quotation | |
| Delete a quotation | destructive |
Credit Notes (4 tools)
Tool | Description | Annotations |
| List credit notes | read-only |
| Get a credit note by ID | read-only |
| Create credit note (supports healthcare sector, external invoice refs) | |
| Get credit note PDF (base64) | read-only |
Vouchers / Cash Receipts (3 tools)
Tool | Description | Annotations |
| List cash receipts (recibos de caja) | read-only |
| Get a cash receipt by ID | read-only |
| Create cash receipt (DebtPayment, AdvancePayment, MiscIncome) |
Purchase Support Documents (4 tools)
Tool | Description | Annotations |
| Get a purchase support document by ID | read-only |
| Create purchase support document (document type DS) | |
| Update a purchase support document | |
| Delete a purchase support document | destructive |
Purchases (5 tools)
Tool | Description | Annotations |
| List purchase invoices | read-only |
| Get a purchase by ID | read-only |
| Create a purchase invoice | |
| Update a purchase | |
| Delete a purchase | destructive |
Payment Receipts / Disbursements (5 tools)
Tool | Description | Annotations |
| List payment receipts (recibos de pago / comprobantes de egreso) | read-only |
| Get a payment receipt by ID | read-only |
| Create payment receipt (DebtPayment, AdvancePayment, Detailed) | |
| Update a payment receipt | |
| Delete a payment receipt | destructive |
Journals / Accounting Entries (3 tools)
Tool | Description | Annotations |
| List accounting journals (comprobantes contables) | read-only |
| Get a journal by ID | read-only |
| Create journal entry (debits must equal credits) |
Webhooks (4 tools)
Tool | Description | Annotations |
| List webhook subscriptions | read-only |
| Subscribe to a webhook event | |
| Update a webhook subscription | |
| Delete a webhook subscription | destructive |
Catalogs (10 tools + account groups above)
Tool | Description |
| Document types (FV, RC, NC, FC, CC, RP, C, DS) |
| Taxes (IVA, Retefuente, ReteIVA, ReteICA, etc.) |
| Payment methods |
| Cost centers |
| Users/sellers |
| Warehouses |
| Price lists (up to 12) |
| Expenses for cash receipt adjustments |
| Miscellaneous income concepts for cash receipts |
| Fixed assets |
Reports (3 tools)
Tool | Description |
| Trial balance report (Excel) |
| Trial balance by third party (Excel) |
| Accounts payable report |
Document Types Reference
Code | Spanish Name | English Name | MCP Support |
| Factura de Venta | Sales Invoice | Full CRUD + PDF/XML/Email/Batch/Annul |
| Recibo de Caja | Cash Receipt | Create + Query |
| Nota Credito | Credit Note | Create + Query + PDF |
| Factura de Compra | Purchase Invoice | Full CRUD |
| Comprobante Contable | Accounting Journal | Create + Query |
| Recibo de Pago/Egreso | Payment Receipt | Full CRUD |
| Cotizacion | Quotation | Full CRUD |
| Documento Soporte | Purchase Support Document | Full CRUD |
Example Usage
The examples below use direct operation names available in the legacy profile. For default v6 tool calls, see the workflow examples.
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",
"payment_method": "04",
"service_plan": "16",
"contract_number": "CONTRACT-2026-001",
"copayment": 150000
}
}
}
}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/
│ ├── cli.ts # stdio / HTTP executable entrypoint
│ ├── index.ts # side-effect-free public library exports
│ ├── mcp-server.ts # MCP server factory and tool registration
│ ├── http-server.ts # Stateless Streamable HTTP application
│ ├── siigo-client.ts # HTTP client for all Siigo API endpoints
│ ├── contracts.ts # exact inferred request contract types
│ ├── schemas/ # strict Zod API contracts
│ ├── tools/ # resource-specific MCP registrations
│ └── types.ts # Siigo response and shared interfaces
├── docs/ # source policy and API coverage matrix
├── test/ # compiled-output Jest contract tests
├── dist/ # Compiled output (ESM)
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.mdBuilding
pnpm buildRunning for Development
pnpm devContributing
Fork the repository
Create a feature branch
Make your changes
Run
pnpm lint && pnpm testto verifySubmit a pull request
License
Support
Siigo API: Contact soporteapi@siigo.com
This MCP server: Create an issue
Links
Available Tools
49 toolssiigo_create_credit_noteC
Create a new credit note
Inputs: creditNote (required).
siigo_create_customerC
Create a new customer
Inputs: customer (required).
siigo_create_invoiceC
Create a new invoice
Inputs: invoice (required).
siigo_create_journalC
Create a new accounting journal
Inputs: journal (required).
siigo_create_payment_receiptC
Create a new payment receipt
Inputs: paymentReceipt (required).
siigo_create_productC
Create a new product
Inputs: product (required).
siigo_create_purchaseC
Create a new purchase
Inputs: purchase (required).
siigo_create_voucherC
Create a new voucher
Inputs: voucher (required).
siigo_delete_invoiceC
Delete an invoice
Inputs: id (required).
siigo_delete_payment_receiptC
Delete a payment receipt
Inputs: id (required).
siigo_delete_productC
Delete a product
Inputs: id (required).
siigo_delete_purchaseC
Delete a purchase
Inputs: id (required).
siigo_get_account_groupsB
Get account groups catalog
Inputs: no named parameters.
siigo_get_accounts_payableC
Get accounts payable report
Inputs: page, page_size.
siigo_get_citiesC
Get cities catalog
Inputs: no named parameters.
siigo_get_cost_centersC
Get cost centers catalog
Inputs: no named parameters.
siigo_get_credit_noteC
Get a specific credit note by ID
Inputs: id (required).
siigo_get_credit_notesC
Get list of credit notes from Siigo
Inputs: page, page_size.
siigo_get_customerB
Get a specific customer by ID
Inputs: id (required).
siigo_get_customersC
Get list of customers from Siigo
Inputs: page, page_size, type.
siigo_get_document_typesB
Get document types catalog
Inputs: type.
siigo_get_fiscal_responsibilitiesC
Get fiscal responsibilities catalog
Inputs: no named parameters.
siigo_get_id_typesB
Get ID types catalog
Inputs: no named parameters.
siigo_get_invoiceC
Get a specific invoice by ID
Inputs: id (required).
siigo_get_invoice_pdfC
Get invoice PDF
Inputs: id (required).
siigo_get_invoicesC
Get list of invoices from Siigo
Inputs: page, page_size, created_start, created_end.
siigo_get_journalC
Get a specific journal by ID
Inputs: id (required).
siigo_get_journalsC
Get list of accounting journals from Siigo
Inputs: page, page_size.
siigo_get_payment_receiptC
Get a specific payment receipt by ID
Inputs: id (required).
siigo_get_payment_receiptsB
Get list of payment receipts from Siigo
Inputs: page, page_size.
siigo_get_payment_typesB
Get payment types catalog
Inputs: document_type.
siigo_get_price_listsB
Get price lists catalog
Inputs: no named parameters.
siigo_get_productC
Get a specific product by ID
Inputs: id (required).
siigo_get_productsC
Get list of products from Siigo
Inputs: page, page_size.
siigo_get_purchaseC
Get a specific purchase by ID
Inputs: id (required).
siigo_get_purchasesC
Get list of purchases from Siigo
Inputs: page, page_size.
siigo_get_taxesC
Get taxes catalog
Inputs: no named parameters.
siigo_get_trial_balanceC
Get trial balance report
Inputs: year (required), month_start (required), month_end (required), includes_tax_difference (required), +2 more.
siigo_get_trial_balance_by_thirdC
Get trial balance by third party report
Inputs: year (required), month_start (required), month_end (required), includes_tax_difference (required), +3 more.
siigo_get_usersB
Get users catalog
Inputs: no named parameters.
siigo_get_voucherB
Get a specific voucher by ID
Inputs: id (required).
siigo_get_vouchersC
Get list of vouchers (cash receipts) from Siigo
Inputs: page, page_size.
siigo_get_warehousesC
Get warehouses catalog
Inputs: no named parameters.
siigo_send_invoice_emailC
Send invoice by email
Inputs: id (required), mail_to (required), copy_to.
siigo_update_customerC
Update an existing customer
Inputs: id (required), customer (required).
siigo_update_invoiceC
Update an existing invoice
Inputs: id (required), invoice (required).
siigo_update_payment_receiptC
Update an existing payment receipt
Inputs: id (required), paymentReceipt (required).
siigo_update_productC
Update an existing product
Inputs: id (required), product (required).
siigo_update_purchaseC
Update an existing purchase
Inputs: id (required), purchase (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Every tool has a clearly distinct purpose targeting specific resources and actions in the Siigo accounting/ERP domain. The naming convention (resource + action) makes it easy to distinguish between operations like create_invoice, get_invoice, update_invoice, and delete_invoice without ambiguity.
All tools follow a perfectly consistent 'siigo_verb_noun' pattern throughout the entire set. The structure is uniform with snake_case, consistent verb choices (create, get, update, delete), and clear resource naming, making the tool set highly predictable and readable.
With 49 tools, this server has far too many tools for typical MCP usage, creating cognitive overhead for agents. While comprehensive for an ERP system, the count feels excessive and could overwhelm agents trying to navigate the surface efficiently.
The tool set provides complete CRUD/lifecycle coverage for all major resources (customers, invoices, products, purchases, etc.), plus extensive catalog/report access and specialized operations like sending invoice emails. No obvious gaps exist for the accounting/ERP domain it serves.
Maintenance
Related MCP Connectors
Read invoices, orders, suppliers and payments; create and update clients and products in CBO.
Read invoices, incomes and expenses; create customers and providers in Cuéntica.
Read invoices, clients, products and stock; create clients and invoices in Facturis Online.
Issue, sign and manage Mexican CFDI 4.0 e-invoices, complements and credit notes.
Related MCP Servers
- AlicenseAqualityDmaintenanceUnofficial MCP server for Siigo Colombian electronic invoicing software that enables AI to manage customers, products, invoices, credit notes, and journals through the Siigo API with configurable safety modes.1932 PyPI1MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with the Siigo API to manage products, customers, and invoices with enterprise-grade security features like RBAC and audit logging. It supports financial reporting operations and secure data handling through the Model Context Protocol.-
- AlicenseAqualityDmaintenanceA 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.44MIT
- FlicenseNot gradedqualityDmaintenancePlataforma administrativa multi-cliente para conectar Siigo con paneles, automatizaciones y agentes de IA mediante MCP Streamable HTTP, ofreciendo herramientas para productos, clientes, cotizaciones e inventario.-