COMPRASAL MCP

Query El Salvador's public procurement data straight from your AI assistant.

This is a Model Context Protocol server that wraps the public COMPRASAL API (comprasal.gob.sv) — the country's electronic public-purchasing system — so you can ask Claude (or any MCP client) things like:

"What did the Ministry of Health award in 2025, and for how much?" "Show me the latest public contracts and their suppliers." "Pull the full detail and stage calendar for process 83743."

All data is public information published by the State under the LACAP procurement law. This server is read-only.

---

What you can ask

Once connected, your assistant gains these tools:

Tool	What it does
search_procurement	Search awarded processes by institution, year, modality, or free text. Returns supplier, amount, dates, code.
get_process_detail	Full detail of one process: amounts, dates, and the complete stage calendar.
get_award_report	Richest view: bidders, planned vs certified amounts, budget codes, signature date.
get_supplier_contracts	A supplier's public-sector track record: contracts won, by company name (bounded recent scan).
list_institutions	Resolve an institution name (e.g. "salud") into its id.
list_modalities / list_states / list_years	Catalogs for building precise filters.

---

Install

Requires Node.js 18+.

git clone https://github.com/glassbit/comprasal-mcp.git
cd comprasal-mcp
npm install
npm run build
npm test

Connect to Cursor

This repo ships a project-level MCP config at .cursor/mcp.json. After npm run build:

1. Open this folder in Cursor.
2. Go to Settings → MCP and enable the comprasal server (or restart Cursor).
3. The assistant can call the COMPRASAL tools in Agent mode.

The config runs node dist/index.js against the live COMPRASAL API (cache off by default). To override globally, add the same block to your user MCP settings.

Connect to Claude Desktop

Add this to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "comprasal": {
      "command": "node",
      "args": ["/absolute/path/to/comprasal-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You'll see the COMPRASAL tools available. Ask it about El Salvador's public spending.

---

Local cache (opt-in)

By default every request goes to the live COMPRASAL API — a fresh clone behaves identically for everyone. You may opt in to a local, per-user response cache to speed up repeated queries within a session:

Variable	Default	Description
COMPRASAL_CACHE_ENABLED	false	Set to true to cache raw API responses on disk
COMPRASAL_CACHE_DIR	.comprasal-cache	Cache directory (gitignored, never committed)
COMPRASAL_CACHE_TTL_MS	3600000 (1 hour)	Entry lifetime; expired entries are deleted on read

The cache is not a shared or committed database — it is created at runtime on your machine only. After TTL expiry, the next request fetches live data again. Disable it anytime with COMPRASAL_CACHE_ENABLED=false.

---

Tests

npm test              # unit + mocked integration only (no network)
npm run test:live     # optional smoke test against real COMPRASAL API (~7s)

Tests cover client-side filters, Zod argument validation, file cache behaviour, and mocked HTTP flows.

---

Notes & caveats

The upstream government API only filters reliably by institution. This is the single most important thing to understand about this tool:

• id_institucion is the only server-side filter that works. Year, free-text search, and date range are silently ignored by the COMPRASAL backend.
• This server compensates by filtering client-side (over the real award date fecha_adjudicacion and text fields), scanning newest-first pages up to a bounded limit.
• Consequence: deep historical queries are not practical. Asking for "all contracts from supplier X since January 2025" or "institution Y in 2024" can require scanning thousands of records at ~7s/page — so those tools return a bounded recent window and clearly say so in a coverage / filtering block. A bounded result is never presented as exhaustive.
• Backend latency is ~7s per request (this is the government server, not the MCP). Tools make one request per page and cap how many pages they scan, so a call may take 10-50s.
• get_supplier_contracts cannot filter by supplier upstream, so it scans the most-recent global records and matches locally. Pass id_institucion when you know it — the scan becomes far faster and deeper.
• Date filters apply to the award date (fecha_adjudicacion) in this server, even though the raw upstream API filters on the process start date.
• get_award_report uses a different id than the other endpoints (a known upstream quirk). Prefer get_process_detail unless you specifically need the bidder/budget breakdown.
• The dataset holds ~100k+ awarded processes, current through 2026. Each process may appear as several rows (one per lot/supplier).
• Tool arguments are validated with Zod before any upstream call; invalid inputs return a clear error without hitting the API.

Why no local database / committed cache?

This server queries the live public API so that anyone who clones it gets identical results with zero setup — no pre-scraped dataset, no shared state in the repo. A committed database would mean either hosting a central server (defeating the "run it yourself" model) or asking every user to scrape COMPRASAL first (hours of work).

An optional, opt-in file cache is available for convenience: it lives in .comprasal-cache/ on your machine only (gitignored), expires after 1 hour, and is off by default. It does not change what a fresh clone returns on first run. A full local-database variant for deep historical analysis remains a possible separate, opt-in project.

Data, source & legality

Data comes from the public COMPRASAL portal (comprasal.gob.sv), accessed through its public, unauthenticated REST API. Public procurement acts are public by law under the LACAP (Ley de Adquisiciones y Contrataciones de la Administración Pública). Public registries are excluded from the scope of El Salvador's Personal Data Protection Law (Decreto 144, 2024, art. 3). This project redistributes already-public information for transparency and research purposes and performs no scraping of authenticated areas.

License

MIT. Not affiliated with or endorsed by the Government of El Salvador.