hilma-mcp

hilma-mcp

MCP (Model Context Protocol) -serveri Suomen julkisille hankintailmoituksille — hankintailmoitukset.fi (Hilma).

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

Kieliversio: Ohjeet suomeksi alla. English instructions further down.

---

Vaatimukset

• Node.js versio 18 tai uudempi
• Claude Desktop tai Claude Cowork (MCP-tuki)
• Hilma AVP API -avain (ks. alla)

---

Asennus

1. Kloonaa repo

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

2. Asenna riippuvuudet ja buildaa

npm install
npm run build

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

3. Luo .env-tiedosto

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:

{
  "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

1. Tai anna se suoraan Claude-konfiguraatiossa:

   {
     "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 -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

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):

{
  "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.

---

Aimiten

Tämä MCP-serveri on toteutettu osana Aimitenin 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
• 📖 Claude Code -opas (suomeksi): aimiten.fi/oppaat/claude-ai
• 🛠️ MCP-palvelimet & integraatiot: aimiten.fi/palvelut
• 👤 Tekijät: Sampsa Sironen (CEO) + Ville Grönlund (Co-Founder)

This MCP server is built and maintained by Aimiten, a Finnish AI consultancy specializing in Claude, Copilot, and Gemini integrations for SMEs.