Meta Agent Tools
PT

Back to the catalog

io.github.Aimiten/hilma-mcp

MCP server for Finnish public procurement notices (Hilma). Built by Aimiten.

Open source Open in the app JSON README (API)

About

MCP server for Finnish public procurement notices (Hilma). Built by Aimiten.

Details

Kind
MCP servers
Topic
Government & public data
Publisher
aimiten
Origin
official
Category
ferramentas
Transport
local
Version
1.1.1
Last push
2026-05-15T09:21:42Z
Repository state
ativo
Language
JavaScript
License
MIT
Added
2026-08-29 03:01:40
Updated
2026-08-29 03:01:40
Origin id
io.github.Aimiten/hilma-mcp

README

# hilma-mcp

MCP (Model Context Protocol) -serveri Suomen julkisille hankintailmoituksille — [hankintailmoitukset.fi](https://hankintailmoitukset.fi) (Hilma).

Mahdollistaa hankintailmoitusten haun suoraan Claude-assistentista ilman erillistä selainta.

> **Kieliversio:** Ohjeet suomeksi alla. English instructions further down.

---

## Vaatimukset

- [Node.js](https://nodejs.org/) versio 18 tai uudempi
- Claude Desktop tai Claude Cowork (MCP-tuki)
- Hilma AVP API -avain (ks. alla)

---

## Asennus

### 1. Kloonaa repo

```bash
git clone https://github.com/Aimiten/hilma-mcp.git
cd hilma-mcp
```

### 2. Asenna riippuvuudet ja buildaa

```bash
npm install
npm run build
```

Tämä luo `dist/index.js`-tiedoston, jota Claude ajaa.

### 3. Luo .env-tiedosto

```bash
cp .env.example .env
```

Avaa `.env` tekstieditorissa ja lisää API-avaimesi:

```
HILMA_API_KEY=oma-avp-read-avain-tähän
HILMA_READ_API_KEY=oma-avp-read-avain-tähän
```

> **Huom:** Molemmat kentät käyttävät **samaa avainta** — `avp-read`-tuote sisältää jo Read API (EForms) -rajapinnan, joten erillistä tilausta ei tarvita.

Hanki avain ilmaiseksi:
1. Mene osoitteeseen https://hns-hilma-prod-apim.developer.azure-api.net/
2. Rekisteröidy tai kirjaudu → **Products → avp-read → Subscribe**
3. Kopioi Primary key Profile-sivulta

> **Huom:** `.env`-tiedostoa ei koskaan commitoida GitHubiin — se on jo `.gitignore`:ssa.

### 4. Lisää Claude-konfiguraatioon

Avaa Claude Desktopin konfiguraatiotiedosto:

| Käyttöjärjestelmä | Polku |
|-------------------|-------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |

Lisää tai muokkaa `mcpServers`-osiota:

```json
{
  "mcpServers": {
    "hilma": {
      "command": "node",
      "args": ["/ABSOLUUTTINEN/POLKU/hilma-mcp/dist/index.js"]
    }
  }
}
```

**Tärkeää:** Korvaa `/ABSOLUUTTINEN/POLKU/hilma-mcp` oikealla polulla omalla koneellasi. Esimerkiksi:
- macOS: `/Users/sinunnimesi/hilma-mcp/dist/index.js`
- Windows: `C:\\Users\\sinunnimesi\\hilma-mcp\\dist\\index.js`

### 4. Käynnistä Claude uudelleen

Hilma ilmestyy connectors-listaan uudelleenkäynnistyksen jälkeen.

---

## API-avain

Serveri **vaatii** oman API-avaimen — sitä ei ole bundlattu koodiin tietoturvasyistä.

1. Rekisteröidy ilmaiseksi: https://hns-hilma-prod-apim.developer.azure-api.net/
2. Lisää avain `.env`-tiedostoon (suositeltu):
   ```
   HILMA_API_KEY=oma-avaimesi-tähän
   ```
3. Tai anna se suoraan Claude-konfiguraatiossa:
   ```json
   {
     "mcpServers": {
       "hilma": {
         "command": "node",
         "args": ["/polku/hilma-mcp/dist/index.js"],
         "env": {
           "HILMA_API_KEY": "oma-avaimesi-tähän"
         }
       }
     }
   }
   ```

---

## Työkalut

| Työkalu | Kuvaus | Vaatii |
|---------|--------|--------|
| `search_notices` | Hae ilmoituksia CPV-koodeilla, hakusanalla, päivämäärällä | HILMA_API_KEY |
| `get_notice_summary` | Yksittäisen ilmoituksen metatiedot noticeId:llä | HILMA_API_KEY |
| `get_expiring_soon` | Ilmoitukset joiden deadline on N päivän sisällä | HILMA_API_KEY |
| `get_notice_full` | Täysi eForms XML + yhteystiedot (BT-502/503/506) | HILMA_READ_API_KEY |

### `search_notices` — Hankintailmoitusten haku

| Parametri | Tyyppi | Kuvaus |
|-----------|--------|--------|
| `search` | string | Vapaatekstihaku. `"*"` = kaikki. |
| `cpv_codes` | string[] | CPV-koodit, esim. `["71200000", "72000000"]`. OR-logiikka. |
| `notice_type` | string | `ContractNotices` / `ContractAwardNotices` / `PlanNotices` |
| `procurement_type` | string | `services` / `works` / `supplies` |
| `procedure_type` | string | `open` / `restricted` / `negotiated` |
| `days` | number | Viimeiset N päivää |
| `hours` | number | Viimeiset N tuntia |
| `top` | number | Max tuloksia (1–100, oletus 20) |

### `get_notice_summary` — Yksittäisen ilmoituksen yhteenveto

| Parametri | Tyyppi | Kuvaus |
|-----------|--------|--------|
| `notice_id` | number | Ilmoituksen numeerinen ID |

Käyttää search-APIa — ei vaadi erillistä tilausta. Palauttaa kaikki metatiedot: tilaaja, deadline, arvo, CPV, portaali-URL.

### `get_expiring_soon` — Lähestyvät deadlinet

| Parametri | Tyyppi | Kuvaus |
|-----------|--------|--------|
| `days` | number | Hae deadlinet seuraavan N päivän sisällä |
| `cpv_codes` | string[] | Rajaa CPV-koodeilla (valinnainen) |

Järjestää tulokset deadlinen mukaan nousevaan järjestykseen.

### `get_notice_full` — Täydet tiedot eForms XML:stä

| Parametri | Tyyppi | Kuvaus |
|-----------|--------|--------|
| `notice_id` | number | Ilmoituksen numeerinen ID |

**Vaatii HILMA_READ_API_KEY** (sama avain kuin HILMA_API_KEY — sisältyy `avp-read`-tilaukseen). Palauttaa:
- Yhteystiedot: BT-502 (nimi), BT-503 (sähköposti), BT-506 (puhelin)
- Tarjousportaalin URL:t
- Koko eForms XML -raakadata

---

## API-viite

Perustuu viralliseen [Hilma API](https://github.com/Hankintailmoitukset/hilma-api) -dokumentaatioon.

- Hakuendpoint: `POST https://api.hankintailmoitukset.fi/avp/eformnotices/docs/search`
- Yksittäinen ilmoitus: `GET https://api.hankintailmoitukset.fi/avp/eformnotices/docs/{noticeId}`
- Autentikointi: `Ocp-Apim-Subscription-Key` -header

---

## English

### Quick install

```bash
git clone https://github.com/Aimiten/hilma-mcp.git
cd hilma-mcp
npm install && npm run build
cp .env.example .env   # then add your API key to .env
```

Get a free API key at: https://hns-hilma-prod-apim.developer.azure-api.net/

Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

Restart Claude. The Hilma connector will appear in the connectors list.

---

## Lisenssi / License

MIT — ks. [LICENSE](LICENSE).

---

## Aimiten

Tämä MCP-serveri on toteutettu osana **[Aimitenin](https://aimiten.fi)** AI-konsultointia. Aimiten Oy auttaa suomalaisia pk-yrityksiä ottamaan tekoälyn (Claude, Copilot, Gemini, n8n) käytäntöön — koulutus, konsultointi ja kevyet Managed Agents -toteutukset.

- 🌐 **Verkkosivu:** [aimiten.fi](https://aimiten.fi)
- 📖 **Claude Code -opas (suomeksi):** [aimiten.fi/oppaat/claude-ai](https://aimiten.fi/oppaat/claude-ai)
- 🛠️ **MCP-palvelimet & integraatiot:** [aimiten.fi/palvelut](https://aimiten.fi/palvelut)
- 👤 **Tekijät:** Sampsa Sironen (CEO) + Ville Grönlund (Co-Founder)

This MCP server is built and maintained by **[Aimiten](https://aimiten.fi)**, a Finnish AI consultancy specializing in Claude, Copilot, and Gemini integrations for SMEs.

More