sii-cli 0.1.0

CLI + MCP server to automate SII Chile interactions

sii

Python CLI + MCP server to automate routine interactions with SII Chile (Servicio de Impuestos Internos) for a single user acting on their own RUT (or an empresa they legally represent).

• sii — the CLI (Typer-based)
• sii-mcp — the Model Context Protocol server (FastMCP, stdio)

The same sii.core engine backs both, so legal and operational guardrails (per-RUT throttling, audit log, credential handling, session lifecycle) apply regardless of which frontend a human or AI assistant uses.

Status

Production-targeted — prod-only by default, no cert sandbox (ADR-016). Implemented end-to-end against the live SII portal:

• auth — interactive login + identity readback (login / status [--refresh] / logout).
• profile — full contribuyente snapshot (incl. PII).
• rcv — Registro de Compras y Ventas: summary (single period, --year, --from/--to range) + list (per-DTE rows) + match (reconcile a folio).
• f29 — Declaración Mensual de IVA: draft (the pre-filled propuesta, read-only).

DTE (factura electrónica, SOAP) and further surfaces (BTE, carpeta tributaria, F22) are tracked in docs/ROADMAP.md and as GitHub issues.

Install

Requires Python 3.12+ and uv.

uv sync
uv run playwright install chromium

Quickstart

Authentication is interactive (ADR-018/019) — the Clave Tributaria is prompted, never passed on the command line or stored in shell history.

# Log in once — prompts for RUT + Clave Tributaria, persists to the OS keyring
uv run sii auth login

# Session + identity
uv run sii auth status              # pure local read of the cached session
uv run sii auth status --refresh    # hits SII, reads identity from Mi Sii
uv run sii profile                  # full contribuyente snapshot (PII; use status -r for the safe subset)

# Registro de Compras y Ventas (COMPRA = received, VENTA = issued)
uv run sii rcv summary --period 2026-05 --side COMPRA
uv run sii rcv summary --year 2026 --side VENTA
uv run sii rcv list --period 2026-05 --type compras --doc-type-code 33
uv run sii rcv match --folio 12345

# F29 (IVA mensual) — read SII's pre-filled propuesta (read-only, never submits)
uv run sii f29 draft --period 2026-05

# Operate on an empresa you legally represent (ADR-015)
uv run sii f29 draft --period 2026-05 --rut 11111111-1

# Sanity check: resolved hostnames + rate limit
uv run sii status

# Close the session cleanly when done (avoids the stale-session block, ADR-011)
uv run sii auth logout

Most commands take --format json (default, pipe to jq) or --format table.

The MCP server runs over stdio (default for Claude Desktop / Claude Code) and exposes the same operations (auth_status, profile, rcv_summary, rcv_list, rcv_match, f29_draft, current_config):

uv run sii-mcp
# Or with the MCP Inspector for debugging:
uv run mcp dev src/sii/mcp/server.py

Methodology

This repository follows Context-First Development (CFD): every architectural and process decision lives as an ADR under docs/decisions/, work units are tracked as GitHub issues with a fixed body template, and PR review cross-checks the diff against the indices rather than scanning full files.

• CLAUDE.md — root index (≤100 lines).
• docs/ARCHITECTURE.md, STACK.md, CONVENTIONS.md, CURRENT_STATUS.md, ROADMAP.md — loaded on demand.
• docs/decisions/ — 20 ADRs covering the three-layer split, single-env (prod), the in-house SII contract, session lifecycle, rate limits, multi-RUT, interactive auth, the GitHub workflow, review philosophy, and the SII wire-contract docs convention.
• docs/sii-contract/ — the observed SII wire contracts per surface (endpoints, payloads, enum legends, captcha posture), one doc per surface following a canonical template (ADR-020).
• .claude/commands/ — slash commands (issue-new, issue-start, review-pr, session-start, session-close, etc.).
• .github/ — PR + issue templates aligned with the ADRs.

CFD itself: https://github.com/albertomarturelo/context-first-development.

Posture

This project automates a user's interaction with their own SII account (or accounts they legally represent). It does not target multi-tenant SaaS use; it does not rotate IPs to evade rate limits; it stores no shared credentials; it logs every operation locally. See docs/decisions/003-tos-posture-own-account-only.md.

Disclaimer. This is an independent, community tool — not affiliated with, authorised by, or endorsed by SII (Servicio de Impuestos Internos). It drives the public taxpayer portal by observing its behaviour (no official non-DTE API exists); SII can change the portal at any time and break it without notice. Provided as is, without warranty (see LICENSE). You are responsible for your use of it and for complying with SII's terms.

License

Apache-2.0 © Alberto Marturelo Lorenzo.