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

{
  "mcpServers": {
    "siigo": {
      "command": "uvx",
      "args": ["siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "your-email@example.com",
        "SIIGO_ACCESS_KEY": "your-access-key",
        "SIIGO_PARTNER_ID": "your-partner-id"
      }
    }
  }
}

Or run directly:

uvx siigo-mcp

Installation

Option 1: uvx (recommended, no install)

uvx siigo-mcp

Option 2: pip/uv install

uv tool install siigo-mcp
# or
pip install siigo-mcp

Option 3: From source

git clone https://github.com/dsfaccini/siigo-mcp.git
cd siigo-mcp
uv sync
uv run siigo-mcp

Prerequisites

uv package manager

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Configuration

Environment Variables

Variable	Required	Description
`SIIGO_USERNAME`	Yes	Siigo account email
`SIIGO_ACCESS_KEY`	Yes	Siigo API access key
`SIIGO_PARTNER_ID`	Yes	Siigo partner ID
`SIIGO_MODE`	No	Tool mode: `read_only` (default), `standard`, `full`
`SIIGO_LAZY_TOOLS`	No	Set to `true` for token-optimized lazy loading
`DRY_RUN`	No	Set to `true` to mock write operations
`LOGFIRE_TOKEN`	No	Pydantic Logfire token for observability

Safety Modes (SIIGO_MODE)

Mode	Tools Available	Use Case
`read_only`	19 tools: `list_`, `get_` only	Safe exploration, testing
`standard`	30 tools: Read + create/update/delete	Normal usage (no DIAN)
`full`	33 tools: All including DIAN operations	Production with caution

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:

Mode	Tokens	Description
Default	~5,600	All 33 tools loaded upfront
Lazy (`true`)	~300	Only 3 discovery tools

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

{
  "env": {
    "SIIGO_LAZY_TOOLS": "true"
  }
}

MCP Client Setup

Claude Desktop

Config location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "siigo": {
      "command": "uvx",
      "args": ["siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "your-email@example.com",
        "SIIGO_ACCESS_KEY": "your-access-key",
        "SIIGO_PARTNER_ID": "your-partner-id"
      }
    }
  }
}

Claude Code

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

{
  "mcpServers": {
    "siigo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "${SIIGO_USERNAME}",
        "SIIGO_ACCESS_KEY": "${SIIGO_ACCESS_KEY}",
        "SIIGO_PARTNER_ID": "${SIIGO_PARTNER_ID}"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "siigo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "${env:SIIGO_USERNAME}",
        "SIIGO_ACCESS_KEY": "${env:SIIGO_ACCESS_KEY}",
        "SIIGO_PARTNER_ID": "${env:SIIGO_PARTNER_ID}"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "siigo": {
      "command": "uvx",
      "args": ["siigo-mcp"],
      "env": {
        "SIIGO_USERNAME": "${env:SIIGO_USERNAME}",
        "SIIGO_ACCESS_KEY": "${env:SIIGO_ACCESS_KEY}",
        "SIIGO_PARTNER_ID": "${env:SIIGO_PARTNER_ID}"
      }
    }
  }
}

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

# Tests that don't require credentials
uv run pytest tests/test_unit.py -v

# Tests with real credentials (read-only)
uv run pytest tests/test_reference.py -v

# All tests with dry-run mode
DRY_RUN=true uv run pytest tests/ -v

Dry-Run Mode

Set DRY_RUN=true to mock all write operations:

DRY_RUN=true uvx siigo-mcp

In dry-run mode:

GET requests work normally (real API)
POST/PUT/DELETE return mock responses without executing

Security Considerations

No human-in-the-loop at MCP layer - This server executes tool calls directly. Guardrails must be implemented in your application layer.
Start with read_only mode - Default mode only exposes read operations. Explicitly set SIIGO_MODE=full only when you understand the risks.
Credentials in config files - MCP configs store credentials. Use environment variable references (${SIIGO_USERNAME}) where supported.
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:

MCP_TRANSPORT=http PORT=8000 uvx siigo-mcp

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

X-Siigo-Username
X-Siigo-Access-Key
X-Siigo-Partner-Id

License

MIT