{
  "markdown": "# hilma-mcp\n\nMCP (Model Context Protocol) -serveri Suomen julkisille hankintailmoituksille — [hankintailmoitukset.fi](https://hankintailmoitukset.fi) (Hilma).\n\nMahdollistaa hankintailmoitusten haun suoraan Claude-assistentista ilman erillistä selainta.\n\n> **Kieliversio:** Ohjeet suomeksi alla. English instructions further down.\n\n---\n\n## Vaatimukset\n\n- [Node.js](https://nodejs.org/) versio 18 tai uudempi\n- Claude Desktop tai Claude Cowork (MCP-tuki)\n- Hilma AVP API -avain (ks. alla)\n\n---\n\n## Asennus\n\n### 1. Kloonaa repo\n\n```bash\ngit clone https://github.com/Aimiten/hilma-mcp.git\ncd hilma-mcp\n```\n\n### 2. Asenna riippuvuudet ja buildaa\n\n```bash\nnpm install\nnpm run build\n```\n\nTämä luo `dist/index.js`-tiedoston, jota Claude ajaa.\n\n### 3. Luo .env-tiedosto\n\n```bash\ncp .env.example .env\n```\n\nAvaa `.env` tekstieditorissa ja lisää API-avaimesi:\n\n```\nHILMA_API_KEY=oma-avp-read-avain-tähän\nHILMA_READ_API_KEY=oma-avp-read-avain-tähän\n```\n\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.\n\nHanki avain ilmaiseksi:\n1. Mene osoitteeseen https://hns-hilma-prod-apim.developer.azure-api.net/\n2. Rekisteröidy tai kirjaudu → **Products → avp-read → Subscribe**\n3. Kopioi Primary key Profile-sivulta\n\n> **Huom:** `.env`-tiedostoa ei koskaan commitoida GitHubiin — se on jo `.gitignore`:ssa.\n\n### 4. Lisää Claude-konfiguraatioon\n\nAvaa Claude Desktopin konfiguraatiotiedosto:\n\n| Käyttöjärjestelmä | Polku |\n|-------------------|-------|\n| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| **Windows** | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\nLisää tai muokkaa `mcpServers`-osiota:\n\n```json\n{\n  \"mcpServers\": {\n    \"hilma\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUUTTINEN/POLKU/hilma-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n**Tärkeää:** Korvaa `/ABSOLUUTTINEN/POLKU/hilma-mcp` oikealla polulla omalla koneellasi. Esimerkiksi:\n- macOS: `/Users/sinunnimesi/hilma-mcp/dist/index.js`\n- Windows: `C:\\\\Users\\\\sinunnimesi\\\\hilma-mcp\\\\dist\\\\index.js`\n\n### 4. Käynnistä Claude uudelleen\n\nHilma ilmestyy connectors-listaan uudelleenkäynnistyksen jälkeen.\n\n---\n\n## API-avain\n\nServeri **vaatii** oman API-avaimen — sitä ei ole bundlattu koodiin tietoturvasyistä.\n\n1. Rekisteröidy ilmaiseksi: https://hns-hilma-prod-apim.developer.azure-api.net/\n2. Lisää avain `.env`-tiedostoon (suositeltu):\n   ```\n   HILMA_API_KEY=oma-avaimesi-tähän\n   ```\n3. Tai anna se suoraan Claude-konfiguraatiossa:\n   ```json\n   {\n     \"mcpServers\": {\n       \"hilma\": {\n         \"command\": \"node\",\n         \"args\": [\"/polku/hilma-mcp/dist/index.js\"],\n         \"env\": {\n           \"HILMA_API_KEY\": \"oma-avaimesi-tähän\"\n         }\n       }\n     }\n   }\n   ```\n\n---\n\n## Työkalut\n\n| Työkalu | Kuvaus | Vaatii |\n|---------|--------|--------|\n| `search_notices` | Hae ilmoituksia CPV-koodeilla, hakusanalla, päivämäärällä | HILMA_API_KEY |\n| `get_notice_summary` | Yksittäisen ilmoituksen metatiedot noticeId:llä | HILMA_API_KEY |\n| `get_expiring_soon` | Ilmoitukset joiden deadline on N päivän sisällä | HILMA_API_KEY |\n| `get_notice_full` | Täysi eForms XML + yhteystiedot (BT-502/503/506) | HILMA_READ_API_KEY |\n\n### `search_notices` — Hankintailmoitusten haku\n\n| Parametri | Tyyppi | Kuvaus |\n|-----------|--------|--------|\n| `search` | string | Vapaatekstihaku. `\"*\"` = kaikki. |\n| `cpv_codes` | string[] | CPV-koodit, esim. `[\"71200000\", \"72000000\"]`. OR-logiikka. |\n| `notice_type` | string | `ContractNotices` / `ContractAwardNotices` / `PlanNotices` |\n| `procurement_type` | string | `services` / `works` / `supplies` |\n| `procedure_type` | string | `open` / `restricted` / `negotiated` |\n| `days` | number | Viimeiset N päivää |\n| `hours` | number | Viimeiset N tuntia |\n| `top` | number | Max tuloksia (1–100, oletus 20) |\n\n### `get_notice_summary` — Yksittäisen ilmoituksen yhteenveto\n\n| Parametri | Tyyppi | Kuvaus |\n|-----------|--------|--------|\n| `notice_id` | number | Ilmoituksen numeerinen ID |\n\nKäyttää search-APIa — ei vaadi erillistä tilausta. Palauttaa kaikki metatiedot: tilaaja, deadline, arvo, CPV, portaali-URL.\n\n### `get_expiring_soon` — Lähestyvät deadlinet\n\n| Parametri | Tyyppi | Kuvaus |\n|-----------|--------|--------|\n| `days` | number | Hae deadlinet seuraavan N päivän sisällä |\n| `cpv_codes` | string[] | Rajaa CPV-koodeilla (valinnainen) |\n\nJärjestää tulokset deadlinen mukaan nousevaan järjestykseen.\n\n### `get_notice_full` — Täydet tiedot eForms XML:stä\n\n| Parametri | Tyyppi | Kuvaus |\n|-----------|--------|--------|\n| `notice_id` | number | Ilmoituksen numeerinen ID |\n\n**Vaatii HILMA_READ_API_KEY** (sama avain kuin HILMA_API_KEY — sisältyy `avp-read`-tilaukseen). Palauttaa:\n- Yhteystiedot: BT-502 (nimi), BT-503 (sähköposti), BT-506 (puhelin)\n- Tarjousportaalin URL:t\n- Koko eForms XML -raakadata\n\n---\n\n## API-viite\n\nPerustuu viralliseen [Hilma API](https://github.com/Hankintailmoitukset/hilma-api) -dokumentaatioon.\n\n- Hakuendpoint: `POST https://api.hankintailmoitukset.fi/avp/eformnotices/docs/search`\n- Yksittäinen ilmoitus: `GET https://api.hankintailmoitukset.fi/avp/eformnotices/docs/{noticeId}`\n- Autentikointi: `Ocp-Apim-Subscription-Key` -header\n\n---\n\n## English\n\n### Quick install\n\n```bash\ngit clone https://github.com/Aimiten/hilma-mcp.git\ncd hilma-mcp\nnpm install && npm run build\ncp .env.example .env   # then add your API key to .env\n```\n\nGet a free API key at: https://hns-hilma-prod-apim.developer.azure-api.net/\n\nAdd to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"hilma\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/hilma-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nRestart Claude. The Hilma connector will appear in the connectors list.\n\n---\n\n## Lisenssi / License\n\nMIT — ks. [LICENSE](LICENSE).\n\n---\n\n## Aimiten\n\nTä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.\n\n- 🌐 **Verkkosivu:** [aimiten.fi](https://aimiten.fi)\n- 📖 **Claude Code -opas (suomeksi):** [aimiten.fi/oppaat/claude-ai](https://aimiten.fi/oppaat/claude-ai)\n- 🛠️ **MCP-palvelimet & integraatiot:** [aimiten.fi/palvelut](https://aimiten.fi/palvelut)\n- 👤 **Tekijät:** Sampsa Sironen (CEO) + Ville Grönlund (Co-Founder)\n\nThis MCP server is built and maintained by **[Aimiten](https://aimiten.fi)**, a Finnish AI consultancy specializing in Claude, Copilot, and Gemini integrations for SMEs.\n",
  "bytes": 6635,
  "sha": "6856b4a467eed9e56da7f81730bc3d49bd5fc439f08c9e27db4ff6da819ac2d6",
  "repo_slug": "aimiten/hilma-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aimiten_hilma_mcp_20d5bbb4/readme"
}