# Finnish Public Procurement (HILMA) MCP

**Search Finland's public tenders with your AI agent.** Contract notices, prior-information
notices, awards, and upcoming procurement plans — from HILMA, Finland's official public
procurement portal. Filter by keyword, CPV code, region, or buyer; get full notice details
in clean, structured form.

> Example: *"Find open cleaning-service tenders in the Helsinki region"* → the agent
> searches HILMA and returns matching notices with buyer, value, and deadline.

This package is a lightweight, open **bridge** that connects any MCP client (Claude Desktop,
etc.) to the hosted, maintained HILMA MCP server on Apify. The bridge holds no data logic —
it forwards your requests to the hosted service, which does the real work and meters usage
to your own Apify account.

## Tools

| Tool | What it does |
|------|--------------|
| `search_tenders` | Search tenders/awards by keyword, CPV, region, buyer, type, date. |
| `get_tender` | Full details for one notice (buyer, value, deadline, lots, winner, documents). |
| `search_procurement_plans` | Browse upcoming procurement plans (early-warning for suppliers). |

Languages: English, Finnish, Swedish (most tenders are Finnish).

## Setup

### 1. Get access + an Apify API token

This bridge calls a **hosted, paid Actor** on Apify. You need your own Apify account and
API token:

1. Open the Actor on the Apify Store: **https://apify.com/nectia/finnish-public-tenders-mcp**
2. Subscribe / rent the Actor (billed per call — pay only for what you use).
3. Copy your token from **Apify Console → Settings → Integrations → API token**.

### 2. Add it to your MCP client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hilma": {
      "command": "npx",
      "args": ["-y", "hilma-mcp-server"],
      "env": {
        "APIFY_API_TOKEN": "PASTE_YOUR_APIFY_TOKEN_HERE"
      }
    }
  }
}
```

Restart your client. No build step, no other keys.

## How it works

```
Your MCP client  ──stdio──►  hilma-mcp-server (this bridge)  ──HTTPS──►  Hosted Actor on Apify  ──►  HILMA API
```

The bridge authenticates to the hosted Actor with your `APIFY_API_TOKEN` and transparently
proxies the tools. Your token stays on your machine; Apify meters the calls to your account.

## Data & attribution

Data from HILMA (hankintailmoitukset.fi), the Finnish public procurement notice service.
This project is not affiliated with or endorsed by HILMA or the operating authorities.

## License

MIT © Nectia Automation. The bridge code is open source; the hosted Actor is a commercial
service.