hilma-mcp

hilma-mcp

フィンランドの公共調達公告向け MCP（Model Context Protocol）サーバー — hankintailmoitukset.fi（Hilma）。

別のブラウザーを使わずに、Claude アシスタントから直接調達公告を検索できます。

言語バージョン： 以下はフィンランド語の手順です。英語の手順は下にあります。

---

要件

• Node.js バージョン 18 以降
• Claude Desktop または Claude Cowork（MCP 対応）
• Hilma AVP API キー（下記参照）

---

インストール

1. リポジトリをクローンする

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

2. 依存関係をインストールしてビルドする

npm install
npm run build

これにより、Claude が実行する dist/index.js ファイルが作成されます。

3. .env ファイルを作成する

cp .env.example .env

テキストエディターで .env を開き、API キーを追加します。

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

注： どちらのフィールドにも同じキーを使用します。avp-read 製品には Read API（EForms）インターフェースが含まれているため、別途サブスクリプションを申し込む必要はありません。

無料でキーを取得する方法：

1. https://hns-hilma-prod-apim.developer.azure-api.net/ にアクセスします
2. 登録またはログインし、Products → avp-read → Subscribe を選択します
3. Profile ページから Primary key をコピーします

注： .env ファイルが GitHub にコミットされることはありません。すでに .gitignore に含まれています。

4. Claude の設定に追加する

Claude Desktop の設定ファイルを開きます。

オペレーティングシステム	パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

mcpServers セクションを追加または編集します。

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

重要： /ABSOLUUTTINEN/POLKU/hilma-mcp を、お使いのコンピューター上の正しいパスに置き換えてください。例：

• macOS：/Users/sinunnimesi/hilma-mcp/dist/index.js
• Windows：C:\\Users\\sinunnimesi\\hilma-mcp\\dist\\index.js

4. Claude を再起動する

再起動後、Hilma がコネクターの一覧に表示されます。

---

API キー

このサーバーでは、セキュリティ上の理由から、独自の API キーが必須です。キーはコードにバンドルされていません。

1. 無料で登録します：https://hns-hilma-prod-apim.developer.azure-api.net/
2. .env ファイルにキーを追加します（推奨）：

   HILMA_API_KEY=oma-avaimesi-tähän
   

3. または、Claude の設定に直接入力します：

   {
     "mcpServers": {
       "hilma": {
         "command": "node",
         "args": ["/polku/hilma-mcp/dist/index.js"],
         "env": {
           "HILMA_API_KEY": "oma-avaimesi-tähän"
         }
       }
     }
   }
   

---

ツール

ツール	説明	必要なもの
search_notices	CPV コード、キーワード、日付で公告を検索します	HILMA_API_KEY
get_notice_summary	noticeId を指定して、個別公告のメタデータを取得します	HILMA_API_KEY
get_expiring_soon	期限が N 日以内に到来する公告を取得します	HILMA_API_KEY
get_notice_full	eForms XML 全体と連絡先（BT-502/503/506）を取得します	HILMA_READ_API_KEY

search_notices — 調達公告の検索

パラメーター	型	説明
search	string	フリーテキスト検索。"*" = すべて。
cpv_codes	string[]	CPV コード。例：["71200000", "72000000"]。OR 条件で検索します。
notice_type	string	ContractNotices / ContractAwardNotices / PlanNotices
procurement_type	string	services / works / supplies
procedure_type	string	open / restricted / negotiated
days	number	過去 N 日間
hours	number	過去 N 時間
top	number	結果の最大数（1～100、デフォルト 20）

get_notice_summary — 個別公告の概要

パラメーター	型	説明
notice_id	number	公告の数値 ID

search API を使用するため、別途サブスクリプションを申し込む必要はありません。発注者、期限、金額、CPV、ポータル URL など、すべてのメタデータを返します。

get_expiring_soon — 期限が近い公告

パラメーター	型	説明
days	number	今後 N 日以内に期限を迎える公告を検索します
cpv_codes	string[]	CPV コードで絞り込みます（任意）

結果は期限の昇順で並べ替えられます。

get_notice_full — eForms XML の完全な情報

パラメーター	型	説明
notice_id	number	通知の数値 ID

HILMA_READ_API_KEY が必要です（HILMA_API_KEY と同じキーです — avp-read サブスクリプションに含まれています）。次の情報を返します：

• 連絡先情報：BT-502（名前）、BT-503（メールアドレス）、BT-506（電話番号）
• 入札ポータルの URL
• eForms XML の生データ全体

---

API リファレンス

公式の Hilma API ドキュメントに基づいています。

• 検索エンドポイント：POST https://api.hankintailmoitukset.fi/avp/eformnotices/docs/search
• 個別の通知：GET https://api.hankintailmoitukset.fi/avp/eformnotices/docs/{noticeId}
• 認証：Ocp-Apim-Subscription-Key ヘッダー

---

英語

クイックインストール

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

無料の API キーはこちらから取得できます：https://hns-hilma-prod-apim.developer.azure-api.net/

Claude Desktop の設定（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

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

Claude を再起動します。コネクターの一覧に Hilma コネクターが表示されます。

---

ライセンス / ライセンス

MIT — LICENSE を参照してください。

---

Aimiten

この MCP サーバーは、Aimiten の AI コンサルティングの一環として開発されました。Aimiten Oy は、フィンランドの中小企業が AI（Claude、Copilot、Gemini、n8n）を実務に導入できるよう、トレーニング、コンサルティング、軽量な Managed Agents の導入を支援しています。

• 🌐 ウェブサイト： aimiten.fi
• 📖 Claude Code ガイド（フィンランド語）： aimiten.fi/oppaat/claude-ai
• 🛠️ MCP サーバーとインテグレーション： aimiten.fi/palvelut
• 👤 開発者： Sampsa Sironen（CEO）+ Ville Grönlund（共同創業者）

この MCP サーバーは、Claude、Copilot、Gemini のインテグレーションを専門とするフィンランドの AI コンサルティング会社、Aimiten が開発・保守しています。中小企業を対象としています。