Siigo MCP Server

Unofficial MCP server for Siigo invoicing software (Colombian electronic invoicing) created by @dsfaccini.

Disclaimers: This is an independent project and is not affiliated with Siigo. The project is at early stages so extensive testing is recommended before production use. The MCP server doesn't include any custom logic beyond calling the documented Siigo API endpoints.

Security Warning: This MCP server gives AI direct access to Siigo API endpoints. By default, only read-only tools are enabled. See Safety Modes before enabling write operations.

Quick Start

Or run directly:

Installation

Option 1: uvx (recommended, no install)

Option 2: pip/uv install

Option 3: From source

Prerequisites

• uv package manager

macOS/Linux:

Windows:

Configuration

Environment Variables

Safety Modes (SIIGO_MODE)

Dangerous tools (only in full mode):

• stamp_invoice - Sends invoice to DIAN (legally binding)

• annul_invoice - Cancels official documents

• send_invoice_email - Sends emails to customers

Lazy Tools Mode (SIIGO_LAZY_TOOLS)

For smaller context models or cost optimization, enable lazy loading:

In lazy mode, LLM uses these meta-tools:

• list_siigo_tools(category?) - Discover available tools

• get_tool_schema(tool_name) - Get full parameter schema

• call_siigo_tool(tool_name, params) - Execute any tool dynamically

MCP Client Setup

Claude Desktop

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Add to ~/.claude.json or .mcp.json in your project:

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json in your project:

VS Code

Add to .vscode/mcp.json:

Available Tools

Read-Only (Safe)

Reference Data:

• get_taxes - Tax configurations

• get_payment_types - Payment methods

• get_document_types - Document types (FV, NC, etc.)

• get_warehouses - Warehouse locations

• get_users - System users

• get_account_groups - Account classifications

Customers:

• list_customers - List with pagination/filters

• get_customer - Get by ID

Products:

• list_products - List with pagination/filters

• get_product - Get by ID

Invoices:

• list_invoices - List with pagination/filters

• get_invoice - Get by ID

• get_invoice_pdf - Download PDF

• get_stamp_errors - DIAN rejection errors

Credit Notes:

• list_credit_notes - List with pagination/filters

• get_credit_note - Get by ID

• get_credit_note_pdf - Download PDF

Journals:

• list_journals - List with pagination/filters

• get_journal - Get by ID

Write Operations (standard mode)

• create_customer, update_customer, delete_customer

• create_product, update_product, delete_product

• create_invoice, update_invoice, delete_invoice

• create_credit_note

• create_journal

Dangerous (full mode only)

• stamp_invoice - Send to DIAN for electronic stamping

• annul_invoice - Annul/cancel an invoice

• send_invoice_email - Email invoice to customer

Development

Running Tests

Dry-Run Mode

Set DRY_RUN=true to mock all write operations:

In dry-run mode:

• GET requests work normally (real API)

• POST/PUT/DELETE return mock responses without executing

Security Considerations

1. No human-in-the-loop at MCP layer - This server executes tool calls directly. Guardrails must be implemented in your application layer.

2. Start with read_only mode - Default mode only exposes read operations. Explicitly set SIIGO_MODE=full only when you understand the risks.

3. Credentials in config files - MCP configs store credentials. Use environment variable references (${SIIGO_USERNAME}) where supported.

4. Production use - Consider using standard mode for most use cases. Only enable full mode when DIAN operations are explicitly needed.

HTTP Mode (Railway Deployment)

For multi-tenant hosting, set MCP_TRANSPORT=http:

In HTTP mode, credentials are passed per-request via headers:

• X-Siigo-Username

• X-Siigo-Access-Key

• X-Siigo-Partner-Id

License

MIT