prozorro-mcp

# prozorro-mcp

<!-- mcp-name: io.github.kotiniiqq/prozorro-mcp -->

An MCP server and a command-line tool for **Prozorro**, Ukraine's public procurement system. It keeps a
local copy of the official open data for the regions you choose. Then you can ask an AI assistant
(Claude, Cursor, VS Code Copilot and others), or the CLI on its own, things like:

- *"Which open tenders for laboratory reagents are in Lviv oblast, and when are the deadlines?"*
- *"What will hospitals in my region buy next month? Show plans that are not tenders yet."*
- *"Who wins most of the flour tenders here, and at what price per kilogram?"*
- *"Who do we usually compete with (EDRPOU 12345678), and how often do we win against them?"*
- *"Any red flags at this buyer: single bidders, one supplier taking most of the money?"*

Every number is computed by code from the data, and the assistant only writes the text. No API keys are
needed: the Prozorro API is public, and nothing here calls an LLM.

> Ukrainian step-by-step guide for non-developers: [docs/guide.uk.md](https://github.com/kotiniiqq/prozorro-mcp/blob/main/docs/guide.uk.md).

## Try it in one minute (bundled demo, no sync)

You need [uv](https://docs.astral.sh/uv/getting-started/installation/) (or plain `pip install prozorro-mcp`):

```bash
uvx prozorro-mcp search --demo --query борошно --status any
```

The demo is a real snapshot of Lviv oblast for one week (5–12 October 2026): 5,479 tenders, 1,120 of
them with public bids, and 1,619 upcoming plans. Contact persons were removed.

## Claude Desktop: one-click extension

Download [prozorro-mcp.mcpb](https://github.com/kotiniiqq/prozorro-mcp/releases/latest/download/prozorro-mcp.mcpb)
and open it (or drag it into Settings → Extensions). Claude Desktop installs Python and the package by
itself, so there is nothing else to install and no config to edit. In the install dialog, type your
oblasts (for example `Львівська, Волинська`) and the days of history.

Your regions download in the background; until the first download finishes, Claude says the data is
not ready and shows the progress. If you leave the settings empty, Claude asks which oblast and how
many days to download. Every start fetches what changed since the last one. To add a region later, ask Claude: *"download Volyn oblast
for the last two weeks"*.

## Connect it to other AI clients

The server runs locally over stdio. Pick your client:

**Claude Code**

```bash
claude mcp add prozorro -- uvx prozorro-mcp serve
```

**Claude Desktop without the extension**: Settings → Developer → Edit Config. The file is
`%APPDATA%\Claude\claude_desktop_config.json` on Windows and
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:

```json
{
  "mcpServers": {
    "prozorro": {
      "command": "uvx",
      "args": ["prozorro-mcp", "serve"]
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`) and **Windsurf, Cline and other clients**: the same `mcpServers` block
as Claude Desktop.

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "prozorro": {
      "type": "stdio",
      "command": "uvx",
      "args": ["prozorro-mcp", "serve"]
    }
  }
}
```

To try it on the demo first, add `"--demo"` after `"serve"`. Restart the client after editing the config.

ChatGPT and claude.ai in the browser only connect to remote servers over HTTPS. See
[HTTP mode](#http-mode).

## Sync your own data

```bash
uvx prozorro-mcp sync --region Львівська --days 7
```

- **Regions** work in any spelling: `Львів`, `львовская`, `Lviv`, `Kyiv city`, `Київська`. Repeat
  `--region` for several. Military units hide their address by law, so their tenders have no region.
  Add them with `--region "без регіону"`.
- **First sync** walks the change feed backwards, newest change first, so tenders that are open right now
  arrive in the first minutes, and stops at the start of the period. A busy
  oblast takes about 20 minutes per week of data (Lviv: about 5,500 tenders and as many plans, roughly
  350 MB on disk), mostly waiting on the public API, which is used
  politely with 5 requests at a time and retries. `--cpv 33` (or `--cpv реактиви`) keeps only your
  categories.
- **Next runs** (`prozorro-mcp sync` with no options) fetch only what changed since the last run.
  Ctrl+C is safe: run the command again and it continues from where it stopped.
- **From the server**: `prozorro-mcp serve --sync-on-start` fetches what changed in the background when the
  client starts it (add `--region` and `--days` to widen the coverage). Before the first sync, the data
  tools return `no_data` with a request to ask the user for an oblast and a period; during a sync,
  results carry `sync_in_progress`.
- **Status**: `prozorro-mcp status` shows what is covered. Data lives in `~/.prozorro-mcp/data.db`; set
  `PROZORRO_MCP_DB` to move it.

## Use it without an AI client

The same numbers, as a table, CSV (opens in Excel with Cyrillic intact) or JSON. Install the command
once with `uv tool install prozorro-mcp`, and then:

```bash
prozorro-mcp search --cpv реактиви --region Львівська            # open tenders, nearest deadline first
prozorro-mcp plans --query "лабораторні" --budget-min 100000    # upcoming purchases
prozorro-mcp flags --buyer 05498849                             # red flags for one buyer
prozorro-mcp watch add "реактиви Львів" --cpv 33696 --region Львівська
prozorro-mcp digest --since 24h --format csv --out digest.csv   # what is new for your saved searches
```

Run `sync` and `digest` every morning with Task Scheduler or cron (the guide shows how), and you have a
daily list of new tenders without opening any website.

## Tools

Eleven tools only read the local database. Each one declares `readOnlyHint: true`,
`destructiveHint: false`, `idempotentHint: true` and `openWorldHint: false`. Three more exist only in the
local stdio server, not in HTTP mode, and are marked for what they do: `sync_data` downloads data
(`readOnlyHint: false`, `openWorldHint: true`), `watch_add` saves a search and `watch_remove` deletes one
(`destructiveHint: true`). The server asks the assistant to start a download only after the user agrees.

| tool | what it returns |
|---|---|
| `coverage` | synced regions, period, counts, last sync; the command to add more |
| `find_entity` | EDRPOU codes of buyers and suppliers by part of a name |
| `search_tenders` | tenders by words, CPV, region, status, amount, deadline, publication date |
| `get_tender` | one tender: items, lots, every bid, the winner, documents with direct links |
| `market_overview` | count and value, competitive share, average bidders, unit-price spread, top buyers and winners |
| `supplier_profile` | wins, buyers, CPVs, win rate, median discount |
| `buyer_profile` | what it buys, from whom, procedure mix, single-bidder share |
| `competitors` | who bids in the same tenders and the head-to-head score |
| `upcoming_plans` | annual-plan items with no tender yet |
| `red_flags` | the four flags below, each with evidence and a link |
| `watch_digest` | new tenders for your saved searches |
| `sync_data` | starts a background download of regions or a longer period; `coverage` shows the progress |
| `watch_add`, `watch_remove` | save or delete a search for `watch_digest`, right from the chat |

When a question needs data that is not synced, for example another oblast or an older period, the
result says so and gives the exact `sync` command. It does not return an empty list that looks like
"nothing exists".

## How the numbers are defined

- **Open tender**: status `active.tendering` or `active.enquiries`, and the deadline has not passed as of
  the last sync. Prozorro sometimes changes the status late.
- **Competitive procedure**: open, below-threshold, price quotation, competitive dialogue, framework
  selection and similar types. `reporting` (a direct contract) and `negotiation` are not competitive.
  The full list is in `src/prozorro_mcp/models.py`.
- **Decided tender**: one that has an active award.
- **Unit price**: award ÷ quantity. It is computed only for tenders with exactly one item, and grouped
  by the full CPV code and unit, so kilograms are never compared with tonnes. Other tenders are counted
  as `excluded`.
- **Win rate**: decided tenders won ÷ decided tenders bid in. Bids become public only after the auction.
- **Discount**: (expected value − award) ÷ expected value, for competitive tenders without lots.

### Red flags

A flag is a reason to look closer, **not proof of wrongdoing**.

| flag | rule (defaults are parameters) |
|---|---|
| `single_bidder` | a competitive procedure that ended with one bidder |
| `supplier_concentration` | one supplier got more than 50% of a buyer's awarded money, with at least 5 awards |
| `price_above_median` | unit price at least 30% above the median of at least 5 comparable tenders (same CPV and unit) |
| `short_tender_period` | tendering shorter than 7 days (open), 15 (EU), 3 (below-threshold, price quotation). This is a heuristic, not a legal check: martial-law rules change often |

## Evals

They run without keys or network, all computed by code: `prozorro-mcp eval --suite all`. The latest
results are in [evals/RESULTS.md](https://github.com/kotiniiqq/prozorro-mcp/blob/main/evals/RESULTS.md).

- **Flags**: 35 labelled cases, including near-threshold negatives such as 29% vs 30% above the median
  or exactly half the money. Precision and recall are 1.0 for every flag.
- **Regions and CPV words**: 94 spellings, 98.9% recognized. The one miss is shown in the results.
- **Reconcile**: buyer and category totals from the analytics are checked against an independent
  recount over the raw JSON of the demo snapshot. 35 aggregates, 0 mismatches.

## HTTP mode

```bash
prozorro-mcp serve --http --host 127.0.0.1 --port 8000      # MCP endpoint: http://127.0.0.1:8000/mcp
```

The same tools are served over streamable HTTP. To reach it from ChatGPT or claude.ai, put it behind a
reverse proxy with HTTPS (Caddy, nginx). Versi