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:
- Mene osoitteeseen https://hns-hilma-prod-apim.developer.azure-api.net/
- Rekisteröidy tai kirjaudu → Products → avp-read → Subscribe
- 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ä.
- Rekisteröidy ilmaiseksi: https://hns-hilma-prod-apim.developer.azure-api.net/
- Lisää avain
.env-tiedostoon (suositeltu):HILMA_API_KEY=oma-avaimesi-tähän - 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.