sri-mcp

# mcp-sri [](https://github.com/smooth-coder/sri-mcp/releases) [](https://github.com/smooth-coder/sri-mcp/commits/main) [](LICENSE) [](https://github.com/smooth-coder) An MCP (Model Context Protocol) server for retrieving Ecuadorian SRI received documents and authorized document XML. ## Features - List received documents from the SRI portal with flexible date filtering (year, month, day) - Download authorized document XML via the SRI SOAP web service using a `claveAcceso` - Headless browser automation via Playwright Firefox (visible mode optional) - CAPTCHA detection — returns a typed error without attempting to solve it - Stateless — no document, report, or credential persistence across calls - Stdio transport — compatible with any MCP client ## Tools | Tool | Requires credentials | Description | | --------------------------- | --------------------------------- | ----------------------------------------------------------------------------------- | | `list_received_documents` | Yes (`SRI_USER` + `SRI_PASSWORD`) | Lists received documents for a given year, with optional month and day filters | | `get_received_document_xml` | No | Retrieves the authorized XML for a single document using its 49-digit `claveAcceso` | ## Tool details ### `list_received_documents` Lists received documents from the SRI portal for a given RUC and date range. **Inputs** | Field | Type | Required | Notes | | ------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `year` | string | yes | One of the 5 years exposed by the SRI portal, newest first (dynamic at server start). Example today: `"2026"`, `"2025"`, `"2024"`, `"2023"`, `"2022"`. | | `month` | string | no | Spanish month name with capitalized first letter: `"Enero"` .. `"Diciembre"`. Omit to query all 12 months. | | `day` | number | no | Integer, 1-31. With `month`, scopes within that month; without `month`, scopes that day-of-month across all 12 months (e.g. `{ year: "2026", day: 15 }` queries the 15th of every month in 2026). | **What it does** 1. Expands the date range into one or more monthly periods (12 periods when only `year` is given). 2. Launches a Firefox browser via Playwright (headless by default; set `SRI_HEADLESS=false` if you want to see it). 3. Logs into the SRI recibidos portal with the configured SRI credentials. 4. For each period: searches by date range, downloads the "Descargar reporte" TXT, and parses it into document records. 5. Returns a merged list of `DocumentRecord` objects, each containing a 49-digit `claveAcceso`. **CAPTCHA_DETECTED behavior:** If the SRI portal presents a captcha during login or search, the tool returns an error result with the captcha message (the tool never attempts to solve captchas). **No persistence:** The browser is always closed in a `finally` block. No documents, reports, or credentials are stored anywhere. ### `get_received_document_xml` Retrieves the authorized XML for a single received document. **Input** | Field | Type | Required | Notes | | ------------- | ------ | -------- | ---------------------------- | | `claveAcceso` | string | yes | 49-digit document access key | **What it does** 1. Calls the SRI `AutorizacionComprobantesOffline` SOAP web service. 2. Returns the `AUTORIZADO` comprobante XML plus a filename (`{claveAcceso}.xml`). **Endpoint:** Defaults to the SRI production URL `https://cel.sri.gob.ec/comprobantes-electronicos-ws/AutorizacionComprobantesOffline`. Override with the `SRI_WS_ENDPOINT` environment variable. **Errors:** A `WEBSERVICE_ERROR` result includes the SRI `estado` and `mensajes`. An invalid (non-49-digit) `claveAcceso` is rejected by input validation before the service is called. ## Setup Two ways to run the server: | | Binary | Bun | | ----------------- | ---------------- | --------------------------- | | Runtime required | None | [Bun](https://bun.sh) ≥ 1.3 | | Best for | Using the server | Contributing / development | | Firefox required¹ | Yes | Yes | ¹ Firefox is only needed for `list_received_documents`. `get_received_document_xml` works without it. ### Option A — Download binary Download the binary for your platform from the [latest release](https://github.com/smooth-coder/sri-mcp/releases/latest): | Platform | File | | ------------------- | ------------------------- | | macOS Apple Silicon | `mcp-sri-darwin-arm64` | | macOS Intel | `mcp-sri-darwin-x64` | | Linux x64 | `mcp-sri-linux-x64` | | Linux arm64 | `mcp-sri-linux-arm64` | | Windows x64 | `mcp-sri-windows-x64.exe` | ```bash # macOS / Linux: make executable chmod +x mcp-sri-darwin-arm64 # Install Playwright Firefox — required for list_received_documents (one-time) npx playwright install firefox ``` > **macOS Gatekeeper**: the binary is unsigned. On first run macOS may block it. Go to System Settings → Privacy & Security → allow it, or run: > > ```bash > xattr -d com.apple.quarantine ./mcp-sri-darwin-arm64 > ``` In the per-client configs below, replace `<binary>` with the absolute path to the downloaded file. ### Option B — Run from source with Bun ```bash git clone https://github.com/smooth-coder/sri-mcp.git cd mcp-sri bun install bun run playwright:install ``` --- ### Claude Desktop Config file: | OS | Path | | ------- | ----------------------------------------------------------------- | | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | **Binary** — merge into the `mcpServers` object: ```json { "mcpServers": { "mcp-sri": { "command": "/absolute/path/to/mcp-sri-darwin-arm64", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` **Bun** — merge into the `mcpServers` object: ```json { "mcpServers": { "mcp-sri": { "command": "bun", "args": ["run", "src/index.ts"], "cwd": "/absolute/path/to/mcp-sri", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` ### Claude Code **Binary** — add via CLI (run once): ```bash claude mcp add mcp-sri \ --command /absolute/path/to/mcp-sri-darwin-arm64 \ --env SRI_USER=your-cedula-or-ruc \ --env SRI_PASSWORD=your-password ``` Or add manually to `~/.claude/settings.json` (global) or `.claude/settings.json` (project-scoped): ```json { "mcpServers": { "mcp-sri": { "command": "/absolute/path/to/mcp-sri-darwin-arm64", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` **Bun** — add via CLI (run once): ```bash claude mcp add mcp-sri \ --command bun \ --args "run /absolute/path/to/mcp-sri/src/index.ts" \ --env SRI_USER=your-cedula-or-ruc \ --env SRI_PASSWORD=your-password ``` Or add manually to `~/.claude/settings.json`: ```json { "mcpServers": { "mcp-sri": { "command": "bun", "args": ["run", "src/index.ts"], "cwd": "/absolute/path/to/mcp-sri", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` ### Cursor Config file: `.cursor/mcp.json` (project-scoped) or `~/.cursor/mcp.json` (global). **Binary:** ```json { "mcpServers": { "mcp-sri": { "type": "stdio", "command": "/absolute/path/to/mcp-sri-darwin-arm64", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` **Bun** — Cursor's stdio config has no `cwd` field, so the repo path goes in `args`: ```json { "mcpServers": { "mcp-sri": { "type": "stdio", "command": "bun", "args": ["run", "/absolute/path/to/mcp-sri/src/index.ts"], "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` If `.cursor/mcp.json` lives inside the repo, `${workspaceFolder}` replaces the hardcoded path: `"args": ["run", "${workspaceFolder}/src/index.ts"]`. ### OpenClaw **Binary:** ```json { "mcpServers": { "mcp-sri": { "command": "/absolute/path/to/mcp-sri-darwin-arm64", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` **Bun:** ```json { "mcpServers": { "mcp-sri": { "command": "bun", "args": ["run", "src/index.ts"], "cwd": "/absolute/path/to/mcp-sri", "env": { "SRI_USER": "your-cedula-or-ruc", "SRI_PASSWORD": "your-password" } } } } ``` ### Verify Restart the client and confirm both tools are listed: `list_received_documents` and `get_received_document_xml`. To test without a full client, run the MCP inspector: ```bash # Binary: npx @modelcontextprotocol/inspector /absolute/path/to/mcp-sri-darwin-arm64 # Bun: npx @modelcontextprotocol/inspector bun run src/index.ts ``` ## Configuration ### Environment variables | Variable | Required | Used by | Description | | ----------------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SRI_USER` | yes\* | `list_received_documents` | SRI portal user (cédula, RUC, or pasaporte). Required only to use `list_received_documents`. | | `SRI_PASSWORD` | yes\* | `list_received_documents` | SRI portal password. Required only to use `list_received_documents`. | | `SRI_HEADLESS` | no | `list_received_documents` | Set to `false` if you want to see the Playwright Firefox browser. Defaults to `true` (headless). Only `true` / `false` are supported; any other value is invalid. | | `SRI_WS_ENDPOINT` | no | `get_received_document_xml` | Overrides the SOAP endpoint for `get_received_document_xml` (defaults to the SRI production URL). | \* Required only for `list_received_documents`. The server starts without them and `get_received_document_xml` works regardless. If `list_received_documents` is called without both set, it returns an error result instead of attempting a login. > Keep credentials in the client config or your environment — never paste them into a chat. The server never logs them. ## Transport This server uses **stdio** transport exclusively. The MCP client spawns the process and communicates over stdin/stdout. There is no HTTP server, no port to bind, and no persistent process to manage — the client owns the lifecycle. To start the server manually (for inspection or debugging): ```bash # Binary: ./mcp-sri-darwin-arm64 # Bun: bun run dev ``` ## Development ### Prerequisites - [Bun](https://bun.sh) 1.3+ - Playwright Firefox browser (installed via the command below) ### Install ```bash bun install bunx playwright install firefox ``` ### Typecheck ```bash bun run typecheck ``` ### Lint ```bash bun run lint ``` ### Format ```bash bun run format:check # or fix everything: bun run format ``` ### Test ```bash bun run test ``` ## Manual verification checklist 1. **Start the server and connect.** Run `bun run dev` (or execute the binary directly) and connect with [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) (or any MCP client). 2. **List documents.** Ensure `SRI_USER` and `SRI_PASSWORD` are set in your environment, then call `list_received_documents` with a year. Confirm the response contains rows with 49-digit `claveAcceso` values. 3. **Get document XML.** Take a `claveAcceso` from step 2 and call `get_received_document_xml`. Confirm the response is valid `AUTORIZADO` XML. 4. **Error cases.** Test the captcha scenario (expect a `CAPTCHA_DETECTED` error) and call `get_received_document_xml` with an invalid clave (expect a web service error). ## Notes - **Stateless:** No document or credential persistence. Every call starts fresh and cleans up after itself. - **Credentials are never logged.** Error messages never include the RUC, username, or password. ## Disclaimer This project is an independent, unofficial tool and is **not affiliated with, endorsed by, or associated with the Servicio de Rentas Internas (SRI) of Ecuador** in any way. This tool interacts with publicly accessible SRI systems solely to retrieve documents that belong to the authenticated user. It is intended for personal, lawful, and responsible use only. **The authors accept no liability for:** - Any misuse of this tool or its outputs. - Any disruption, degradation, or unintended impact on SRI systems. - Any consequences arising from use that violates SRI's terms of service or applicable Ecuadorian law. Users are solely responsible for ensuring their use of this tool complies with all applicable laws and regulations. This tool is designed to make a minimal number of requests consistent with its intended use — it does not perform bulk scraping, stress testing, or any action intended to degrade SRI infrastructure.