MCP server for Finnish public procurement notices (Hilma). Built by Aimiten.
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.
git clone https://github.com/Aimiten/hilma-mcp.git
cd hilma-mcp
npm install
npm run build
Tämä luo dist/index.js-tiedoston, jota Claude ajaa.
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:
Huom:
.env-tiedostoa ei koskaan commitoida GitHubiin — se on jo.gitignore:ssa.
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:
/Users/sinunnimesi/hilma-mcp/dist/index.jsC:\\Users\\sinunnimesi\\hilma-mcp\\dist\\index.jsHilma ilmestyy connectors-listaan uudelleenkäynnistyksen jälkeen.
Serveri vaatii oman API-avaimen — sitä ei ole bundlattu koodiin tietoturvasyistä.
.env-tiedostoon (suositeltu):
HILMA_API_KEY=oma-avaimesi-tähän
{
"mcpServers": {
"hilma": {
"command": "node",
"args": ["/polku/hilma-mcp/dist/index.js"],
"env": {
"HILMA_API_KEY": "oma-avaimesi-tähän"
}
}
}
}
| 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:
Perustuu viralliseen Hilma API -dokumentaatioon.
POST https://api.hankintailmoitukset.fi/avp/eformnotices/docs/searchGET https://api.hankintailmoitukset.fi/avp/eformnotices/docs/{noticeId}Ocp-Apim-Subscription-Key -headergit 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.
MIT — ks. LICENSE.
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.
This MCP server is built and maintained by Aimiten, a Finnish AI consultancy specializing in Claude, Copilot, and Gemini integrations for SMEs.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y hilma-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-aimiten-hilma-mcp": {
"command": "npx",
"args": [
"-y",
"hilma-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencehilma-mcpnpmio.github.Aimiten/hilma-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.