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.
{
"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-mcpuvx siigo-mcpuv tool install siigo-mcp
# or
pip install siigo-mcpgit clone https://github.com/dsfaccini/siigo-mcp.git
cd siigo-mcp
uv sync
uv run siigo-mcp- uv package manager
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"| 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 |
| 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 documentssend_invoice_email- Sends emails to customers
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 toolsget_tool_schema(tool_name)- Get full parameter schemacall_siigo_tool(tool_name, params)- Execute any tool dynamically
{
"env": {
"SIIGO_LAZY_TOOLS": "true"
}
}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"
}
}
}
}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}"
}
}
}
}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}"
}
}
}
}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}"
}
}
}
}Reference Data:
get_taxes- Tax configurationsget_payment_types- Payment methodsget_document_types- Document types (FV, NC, etc.)get_warehouses- Warehouse locationsget_users- System usersget_account_groups- Account classifications
Customers:
list_customers- List with pagination/filtersget_customer- Get by ID
Products:
list_products- List with pagination/filtersget_product- Get by ID
Invoices:
list_invoices- List with pagination/filtersget_invoice- Get by IDget_invoice_pdf- Download PDFget_stamp_errors- DIAN rejection errors
Credit Notes:
list_credit_notes- List with pagination/filtersget_credit_note- Get by IDget_credit_note_pdf- Download PDF
Journals:
list_journals- List with pagination/filtersget_journal- Get by ID
create_customer,update_customer,delete_customercreate_product,update_product,delete_productcreate_invoice,update_invoice,delete_invoicecreate_credit_notecreate_journal
stamp_invoice- Send to DIAN for electronic stampingannul_invoice- Annul/cancel an invoicesend_invoice_email- Email invoice to customer
# 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/ -vSet DRY_RUN=true to mock all write operations:
DRY_RUN=true uvx siigo-mcpIn dry-run mode:
- GET requests work normally (real API)
- POST/PUT/DELETE return mock responses without executing
-
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=fullonly 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
standardmode for most use cases. Only enablefullmode when DIAN operations are explicitly needed.
For multi-tenant hosting, set MCP_TRANSPORT=http:
MCP_TRANSPORT=http PORT=8000 uvx siigo-mcpIn HTTP mode, credentials are passed per-request via headers:
X-Siigo-UsernameX-Siigo-Access-KeyX-Siigo-Partner-Id
MIT