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

这会创建 dist/index.js 文件，供 Claude 运行。

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 帮助芬兰中小企业将人工智能（Claude、Copilot、Gemini、n8n）付诸实践 — 提供培训、咨询和轻量级托管 Agent 实施服务。

• 🌐 网站： aimiten.fi
• 📖 Claude Code 指南（芬兰语）： aimiten.fi/oppaat/claude-ai
• 🛠️ MCP 服务与集成： aimiten.fi/palvelut
• 👤 创建者： Sampsa Sironen（CEO）+ Ville Grönlund（联合创始人）

此 MCP 服务由 Aimiten 构建并维护。Aimiten 是一家芬兰 AI 咨询公司，专门为中小企业提供 Claude、Copilot 和 Gemini 集成服务。