sii (TypeScript)

In English: a TypeScript monorepo (core library + CLI + MCP server) that automates routine interactions with Chile's tax authority (SII) for a user acting on their own tax ID and the companies they are authorised to represent. Designed for Claude Code and Claude Desktop. The README below is in Spanish; the code, ADRs and wire-contract docs are the substance - see Engineering highlights for the architecture at a glance.

TypeScript core + CLI + MCP server to automate routine interactions with Chile's SII, for a user acting on their own RUT and the companies they are authorized to represent. Designed for use in both Claude Code and Claude Desktop.

A from-scratch TypeScript rewrite of the proven sii-cli (Python): the SII knowledge and the guardrails are ported; the code is written anew.

⚠️ Unofficial tool. This project is not affiliated with or endorsed by the SII. It is provided "as is" (see LICENSE), with no warranty of any kind. Each user is responsible for complying with the SII's terms of service and Chilean law. It automates a public agency's portal: use it judiciously (the account gets locked after failed attempts; never retry after a lockout).

Status

Read surfaces operational and validated live: authentication (auth), representation (operate), RCV, F22 (status / form / observations / history), F29 (Phase 1), BTE/BHE, authorized DTE (public query), whoami, and administrative requests (SISPAD). First write surface: bte emit (issuing Electronic Fee Receipts). See the details in docs/CURRENT_STATUS.md and the full checklist in docs/ROADMAP.md.

Related MCP server: mcp-sii

Structure

packages/
  core/   @dostertags/sii-core   Núcleo de dominio (librería Node). Las superficies llaman solo a sus tasks.
  cli/    @dostertags/sii-cli     CLI humana (terminal). También lo que Claude Code corre vía Bash.
  mcp/    @dostertags/sii-mcp     Servidor MCP (stdio). El punto de integración para Claude Code y Claude Desktop.
docs/                  Capa de contexto CFD (ARCHITECTURE, CONVENTIONS, ADRs…).

A single core (@dostertags/sii-core) backs both surfaces, so all legal and operational guardrails (throttling, auditing, credential handling, the operate-centric identity model) apply regardless of surface. External dependencies (portal driver, secrets, session, audit, clock) live behind injectable seams so that tests never touch the real SII. See docs/ARCHITECTURE.md.

How to use it with Claude

• Claude Desktop — connect the MCP server (sii-mcp, stdio) via claude_desktop_config.json.

• Claude Code — connect the same MCP (.mcp.json / claude mcp add), and/or let Claude Code use the CLI directly through Bash.

The Clave Tributaria never reaches the LLM or disk in plaintext: browser login (cookies-only) — no MCP tool receives a password. See ADR-006.

Installation and usage

To use it (without cloning the repo). Requires Node ≥ 20. For development, see Development.

# 1) Instala la CLI y el servidor MCP
npm i -g @dostertags/sii-cli @dostertags/sii-mcp

# 2) Instala el navegador que usa el login (una sola vez, ~100–150 MB)
npx playwright install chromium

# 3) Inicia sesión — abre tu navegador en la página REAL del SII;
#    tecleas tu RUT + Clave ahí. La Clave nunca llega al modelo ni a disco.
sii auth login

# 4) Úsalo desde la terminal
sii peticiones list            # ¿tengo trámites detenidos ("en espera de Antecedentes")?
sii rcv summary 2026-05        # resumen del RCV de compras
sii f29 overview 2026          # posición de IVA mes a mes

Connecting the MCP to Claude

The server is stdio (no hosting required): Claude launches it as a process.

Claude Desktop — add to claude_desktop_config.json and restart the app (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "sii": { "command": "sii-mcp" }
  }
}

Claude Code — one command:

claude mcp add sii -- sii-mcp

Then ask it in natural language (e.g., "what's the status of my session?" or "show me the purchases RCV for 2026-05"). If you haven't logged in yet, run sii auth login first (or ask Claude for the auth_login tool, which opens your browser). The read tools change nothing; issuing a BHE requires explicit confirmation.

Playwright is the only heavyweight dependency: sii uses it for browser login (cookies-only, ADR-006). That's why step 2 (npx playwright install chromium) is mandatory the first time; the npm package does not download browsers automatically.

Capabilities

Both surfaces expose the same operations against the SII (a single core): the MCP offers them as tools to Claude; the CLI, as sii … commands.

Via MCP (Claude Desktop / Claude Code)

Claude sees the operations as tools with per-tool configurable permission (read vs write). The write ones —login/logout, operate as— remain controlled.

Issuing a BHE via MCP is DISABLED by default (ADR-026). No argument-based check can protect a destructive tool exposed to a model, because the model writes all the arguments: that's why bte_emit is simply not registered unless the operator sets SII_MCP_ALLOW_WRITES=1 in the env block of the MCP client. Without that, the tool doesn't appear in the list and can't be invoked. To issue, use the CLI.

Prompt examples (natural language; Claude picks the tool):

• "What's the status of my session and which RUT am I operating as?" → auth_status

• "Show me the summary of the purchases RCV for period 2026-05." → rcv_summary

• "List the sales detail of the RCV for 2026-05." → rcv_list

• "Give me all the documents in the purchases RCV for 2026-05 in a single table." → rcv_all

• "How did my income tax return (F22) for tax year 2025 turn out?" → f22_status / f22_formulario

• "Do I have observations on the F22 for 2025?" → f22_observaciones

• "What is my month-by-month VAT position on the F29 during 2026?" → f29_overview

• "Give me the F29 proposal for May 2026, grouped by line." → f29_formulario

• "Which tax documents is RUT 77.777.777-7 authorized to issue?" → dte_authorized (public, no login)

• "List the fee receipts I received in June 2026." → bte_list

• "Do I have administrative requests held up at the SII (awaiting background info)?" → peticiones_list

• "Who am I registered as — legal name and email?" → whoami

• "Simulate a fee receipt of $500,000 for a client (without issuing)." → bte_emit_preview

• "Switch to operating as the company I represent." → operate

Issuing a real BHE (bte_emit) is not available via MCP unless you explicitly enable it (SII_MCP_ALLOW_WRITES=1, ADR-026). When enabled, it requires a confirmacion minted by the preview: single-use, expires in 10 minutes, and tied to the hash of that exact receipt, so it can't be invented or moved to another amount. Also, bte_emit via MCP does not send emails —sending the PDF to an arbitrary address is an exfiltration vector and stayed CLI-only. The login opens your browser on the real SII page — the Clave never reaches the model.

Via CLI (sii)

JSON output by default (pipeable to jq); --human for reading. The operando como … header goes to STDERR.

The session-keyed surfaces (f22, f29, bte) always read the session's principal (without --rut); the body-RUT (rcv) accepts --rut / operate to reach a represented company (ADR-005).

Identity model

A single active account at a time (switching accounts = logout → login). Within the session, a person account uses the operate pointer to choose which RUT it acts on behalf of (itself by default, or a company it represents). Company accounts don't represent anyone. See ADR-005.

Development

pnpm install         # instalar dependencias
pnpm build           # tsc -b (typecheck + build de todos los paquetes)
pnpm test            # vitest
pnpm lint            # eslint
pnpm format          # prettier

Requires Node >=20 and the pnpm pinned in packageManager (package.json).

Methodology

The repo runs under Context-First Development (CFD): decisions-before-code (ADRs), a context layer that every session reads first, and slash commands in .claude/commands/ (/session:start, /session:close, /decision:new, /issue:new, /issue:start, /review-pr, /context:validate). See ADR-001.

Security

Never upload secrets or real PII (RUT, Clave, cookies, names, amounts). To report a vulnerability and review the security posture, read SECURITY.md.

Contributing

Contributions are welcome — start with CONTRIBUTING.md and the context layer in docs/.

Engineering highlights

The largest project in this portfolio: 333 TypeScript files, ~62k lines, 132 test files (1,178 tests), 48 ADRs.

Skills demonstrated: monorepo architecture, dependency inversion, hermetic testing, browser automation, HTML/JSON wire-contract reverse engineering, MCP server implementation, threat modelling for LLM-callable tools, and decision documentation.

Legal notice and terms of use

• Unofficial project. Not affiliated with, sponsored by, or endorsed by the Servicio de Impuestos Internos or any agency of the State of Chile. "SII" is used only to describe which system it interoperates with.

• Automates a third-party portal. It works against an observed interface, not against a public API with a stable contract: the portal may change without notice and stop working, and the SII may restrict or block automated access. Use it only with your own accounts or those you are authorized to represent.

• Tax responsibility remains yours. This tool reads and presents data; it is not tax, accounting, or legal advice. Always verify against the official portal before making decisions, filing, or paying. Filing errors, deadlines, and fines are the user's responsibility.

• bte_emit issues documents with legal validity. That is why it is disabled by default and only appears if the operator sets SII_MCP_ALLOW_WRITES=1. Issuing a boleta (sales receipt) is a legal act: review the preview before confirming.

• Tools exposed to a model (MCP). An LLM can receive untrusted text from the portal itself. State-changing tools are behind an explicit opt-in for that reason; keep that criterion if you add others.

• No warranty. Provided "as is", without any warranty of any kind (see LICENSE).

License

MIT © 2026 Diego Ostertag. See ADR-018.