ckan-mcp-server

CKAN MCP 服务

让任何 CKAN 开放数据门户都能成为对话对象。

让你的 AI 助手直接访问任何 CKAN 开放数据门户——搜索数据集、浏览组织、查询表格数据并读取元数据，全程使用自然语言。

CKAN 是全球大多数公共开放数据门户背后的开源平台（意大利的 dati.gov.it、美国的 data.gov、加拿大的 open.canada.ca 等）。浏览这些门户通常需要了解它们的结构、API 和搜索语法。这个 MCP 服务消除了这一障碍：连接后，你的 AI 工具就能代你完成所有操作。

开放标准与开源让这一切成为可能。 CKAN 提供文档齐全的公共 API。元数据遵循 DCAT——用于描述数据集的 W3C 开放标准。两者都可免费使用、免费构建，并由开放社区维护。本服务正是建立在这一基础之上。

适合哪些人使用？ 所有人。寻找数据以核实报道的记者。探索公共数据集的研究人员。查看所在机构发布了哪些数据的公务人员。构建数据管道的开发者。无需了解 CKAN。

已获 AgID 采用——意大利数字化局 AgID 已复用本项目，作为其工作的一部分，旨在通过 AI 让公共开放数据更易获取、更及时，也更便于查询。

两种使用方式——选择适合你的方式：

	选项 A：本地安装	选项 B：无需安装
方式	npm install -g @aborruso/ckan-mcp-server	将你的工具指向托管的 HTTP 端点
适用场景	在你的设备上运行，可配合任何本地工具使用	快速开始，零配置
请求配额	无共享配额	共享配额为每天 100k 次请求

托管端点：https://ckan-mcp-server.andy-pr.workers.dev/mcp

建议：选项 B 非常适合快速入门，无需配置即可体验。熟悉本服务的功能后，切换到选项 A（本地安装）即可无限使用，且没有共享配额限制。

👉 想探索代码库？AI 生成的 DeepWiki是很好的起点。

许可证：MIT——完整详情请参阅 LICENSE。第三方声明：NOTICE.md。

---

⚖️ 限制

本地服务和托管服务使用相同的工具和输出上限。托管端点还受上方所示的共享请求配额限制。

区域	默认值	上限或配置
工具输出	50,000 个字符	固定的全服务上限
ckan_datastore_search 行数	100	32,000（0 仅返回列名）
每页 ckan_package_search 结果数	10	1,000
ckan_find_relevant_datasets 结果数	10	50
注入的 sparql_query 行数	25	注入时为 1,000；自行提供 LIMIT 的查询不受限制
ckan_tag_list 结果数	100	1,000
ckan_find_portals 结果数	10	50
HTTP 响应正文	32 MiB	本地 Node.js 部署可通过 CKAN_MAX_RESPONSE_BYTES 配置
解压后的响应正文	64 MiB	本地 Node.js 部署可通过 CKAN_MAX_DECOMPRESSED_BYTES 配置

超出输出上限的文本和 Markdown 响应会被截断，并附带截断说明。JSON 响应仍可解析：服务端会缩减已知结果数组，并通过 _truncated 和 _original_count 标记响应；如果响应仍然无法容纳，则会将其替换为一个包含 _truncated 和说明性 _error 的小对象。两个通道发送的负载具有相同的上限，因此读取 structuredContent 的客户端看到的内容与文本完全一致，包括截断标记。需要完整结果集时，请使用分页或缩小查询范围。

---

🔌 在你喜欢的工具中使用

ChatGPT | Claude Desktop | Claude Code | Le Chat (Mistral) | Perplexity Pro | Gemini CLI | VS Code | Codex CLI

此服务适用于任何兼容 MCP 的客户端。以下部分介绍了一些最受欢迎的客户端——如果列表中没有你的工具，请查阅其文档，了解 MCP 配置，并使用相同的端点 URL 或命令。

以下所有示例均适用于本地安装和托管端点。两种方式不同时，会分别列出。

使用本地安装？ 你需要先安装服务——请参阅本地运行。

ChatGPT

需要 ChatGPT Plus、Team 或 Enterprise 方案。

1. 打开个人资料菜单，然后进入 Settings → Apps → Advanced settings
2. 启用 Developer mode
3. 点击 Create app（右上角）
4. 填写表单：
   • Name： CKAN MCP Server
   • Description： 搜索 CKAN 开放数据门户中的数据集
   • MCP Server URL： https://ckan-mcp-server.andy-pr.workers.dev/mcp
   • Authentication： No Auth
   • 勾选确认框，然后点击 Create
5. 在新聊天中，点击 + → More，然后选择 CKAN MCP Server

如需查看带截图的分步指南，请参阅完整的 ChatGPT 指南。

Claude Desktop

使用托管端点（无需安装）——通过连接器界面：

1. 打开 Claude Desktop，然后进入 Settings → Integrations
2. 点击 Add custom integration
3. 填写详细信息：
   • Name： CKAN MCP Server
   • MCP Server URL： https://ckan-mcp-server.andy-pr.workers.dev/mcp
4. 点击 Add 保存
5. 打开新聊天，点击 +，选择 Integrations，然后启用 CKAN MCP Server
6. Claude 询问是否使用工具时，点击 Allow（或 Always allow）

如需查看带截图的详细指南，请参阅完整的 Claude 指南。

使用托管端点（无需安装）——通过配置文件：

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ckan": {
      "url": "https://ckan-mcp-server.andy-pr.workers.dev/mcp"
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "ckan": {
      "command": "npx",
      "args": ["@aborruso/ckan-mcp-server@latest"]
    }
  }
}

Claude Code

使用托管端点（无需安装）：

claude mcp add -s user -t http ckan https://ckan-mcp-server.andy-pr.workers.dev/mcp

使用本地安装：

claude mcp add -s user ckan npx @aborruso/ckan-mcp-server@latest

--scope user 会让所有项目都能使用此服务器，而不仅限于当前项目。

若要仅为特定项目添加，请在项目文件夹中运行命令，并省略 --scope user 标志：

claude mcp add --transport http ckan https://ckan-mcp-server.andy-pr.workers.dev/mcp

Le Chat（Mistral）

1. 在左侧边栏中，点击 Intelligence，然后选择 Connectors
2. 点击 + Add Connector
3. 选择 Custom MCP Connector 选项卡并填写详细信息：
   • Name： CKAN
   • Connector Server： https://ckan-mcp-server.andy-pr.workers.dev/mcp
4. 点击 Connect 保存
5. 打开新聊天，点击 +，然后点击 Connectors，并启用 CKAN

如需查看带截图的分步指南，请参阅完整的 Le Chat 指南。

Perplexity Pro

需要 Perplexity Pro 账户。

1. 点击消息输入栏中的“+”（附件）图标，然后选择 Connectors & sources
2. 点击 Connect external app
3. 填写详细信息：
   • Name： CKAN MCP Server
   • MCP Server URL： https://ckan-mcp-server.andy-pr.workers.dev/mcp
   • Authorization Type： No Authentication
   • Connection Type： HTTP Streamable
4. 勾选确认框并点击 Save
5. 在新聊天中，点击 + → Connectors & sources，并启用 ckan_mcp_server

如需查看带截图的分步指南，请参阅完整的 Perplexity 指南。

Gemini CLI

gemini mcp add -s user -t http ckan https://ckan-mcp-server.andy-pr.workers.dev/mcp

或者手动添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "ckan": {
      "httpUrl": "https://ckan-mcp-server.andy-pr.workers.dev/mcp"
    }
  }
}

VS Code

添加到用户设置或 .vscode/settings.json：

使用托管端点（无需安装）：

{
  "mcpServers": {
    "ckan": {
      "url": "https://ckan-mcp-server.andy-pr.workers.dev/mcp",
      "type": "http"
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "ckan": {
      "command": "npx",
      "args": ["@aborruso/ckan-mcp-server@latest"]
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

使用托管端点（无需安装）：

[mcp_servers.ckan]
url = "https://ckan-mcp-server.andy-pr.workers.dev/mcp"

使用本地安装：

[mcp_servers.ckan]
command = "npx"
args = ["-y", "@aborruso/ckan-mcp-server@latest"]

---

🖥️ 本地运行

选项 1 — 通过 npm 安装

最快的方式。全局安装软件包后，即可立即将其作为命令使用：

npm install -g @aborruso/ckan-mcp-server

服务器将以 ckan-mcp-server 的名称提供，也可以通过以下命令直接运行，无需安装：

npx @aborruso/ckan-mcp-server@latest

选项 2 — 克隆并构建

适用于开发，或需要运行尚未发布的最新代码时：

git clone https://github.com/ondata/ckan-mcp-server.git
cd ckan-mcp-server
npm install
npm run build
node dist/index.js

选项 3 — Docker

感谢 @piersoft，你也可以通过 Docker 运行服务器：

git clone https://github.com/ondata/ckan-mcp-server.git
cd ckan-mcp-server
docker compose up --build -d

MCP 服务将在 http://localhost:3000/mcp 上提供。完整详情（包括如何将 Claude Desktop 连接到容器）请参阅 docker/README.md。

---

🛠️ 可用工具

搜索与发现

• ckan_package_search：使用 Solr 查询搜索数据集
• ckan_find_relevant_datasets：按相关性评分对数据集进行排序
• ckan_package_show：查看数据集的完整详情
• ckan_tag_list：列出标签及其数量

组织

• ckan_organization_list：列出所有组织
• ckan_organization_show：查看组织详情
• ckan_organization_search：按名称搜索组织

群组

• ckan_group_list：列出群组
• ckan_group_show：查看群组详情
• ckan_group_search：按名称搜索群组

DataStore

• ckan_datastore_search：查询表格数据
• ckan_datastore_search_sql：对 DataStore 执行 SQL 查询

质量指标

• ckan_get_mqa_quality：获取 dati.gov.it 数据集的 MQA 质量评分（方法版本 v2，范围为 0-7.5，并带有等级区间），以及最能提升评分的未通过指标
• ckan_get_mqa_quality_details：列出 dati.gov.it 数据集的所有未通过 MQA 指标，按 FAIR 维度分组，并显示 DCAT-AP 属性、权重和增益

###门户发现

• ckan_find_portals：按国家、语言或主题发现全球 CKAN 门户（使用 datashades.info 的实时注册表，其中约有 950 个门户）

目录分析

• ckan_analyze_datasets：搜索数据集并检查可查询资源的 DataStore 架构
• ckan_catalog_stats：门户统计概览（总数、按类别、格式和组织划分的明细）

SPARQL

• sparql_query：对任意公开的 SPARQL 端点执行 SPARQL SELECT 查询

实用工具

• ckan_status_show：验证服务器状态

---

📎 MCP 资源模板

通过 ckan:// URI 方案直接访问数据：

• ckan://{server}/dataset/{id} - 数据集元数据
• ckan://{server}/resource/{id} - 资源元数据和下载 URL
• ckan://{server}/organization/{name} - 组织详情
• ckan://{server}/group/{name}/datasets - 按群组（主题）获取数据集
• ckan://{server}/organization/{name}/datasets - 按组织获取数据集
• ckan://{server}/tag/{name}/datasets - 按标签获取数据集
• ckan://{server}/format/{format}/datasets - 按资源格式获取数据集（res_format + distribution_format）

示例：

ckan://dati.gov.it/dataset/vaccini-covid
ckan://demo.ckan.org/resource/abc-123
ckan://data.gov/organization/sample-org
ckan://dati.gov.it/group/ambiente/datasets
ckan://dati.gov.it/organization/regione-toscana/datasets
ckan://dati.gov.it/tag/turismo/datasets
ckan://dati.gov.it/format/csv/datasets

---

💡 使用示例

自然语言对话

连接后，只需使用日常语言提问，无需查询语法：

“在 dati.gov.it 搜索有关米兰空气质量的数据集，然后总结每个数据集的内容——时间范围、许可证和最佳下载格式。”

服务器会找到 31 个数据集，按结构模式分组，并返回清晰的摘要——包括系列名称、涵盖年份、发布者和格式。无需了解 CKAN。

---

以下示例展示了自然语言请求，以及 LLM 在内部生成并发送到 CKAN 门户的实际工具调用。你不需要自己编写这些查询——这里展示它们是为了说明你的问题在后台如何转换。

搜索数据集（自然语言：“搜索人口数据集”）

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "popolazione",
  rows: 20
})

长 OR 查询时强制使用文本字段解析器（自然语言：“查找酒店或住宿数据集”）

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "hotel OR alberghi OR \"strutture ricettive\" OR ospitalità OR ricettività",
  query_parser: "text",
  rows: 0  // returns only the total count, no dataset records — useful to check how many results match before fetching them
})

注意：使用 query_parser: "text" 时，查询中的 Solr 特殊字符会自动转义。

按相关性排列数据集（自然语言：“查找与城市交通最相关的数据集”）

ckan_find_relevant_datasets({
  server_url: "https://www.dati.gov.it/opendata",
  query: "mobilità urbana",
  limit: 5
})

按组织筛选（自然语言：“显示托斯卡纳大区的近期数据集”）

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  fq: "organization:regione-toscana",
  sort: "metadata_modified desc"
})

使用分面获取统计信息（自然语言：“显示按组织、标签和格式划分的统计信息”）

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  facet_field: ["organization", "tags", "res_format"],
  rows: 0  // skip dataset records, return only the facet counts
})

列出标签（自然语言：“显示与健康相关的热门标签”）

ckan_tag_list({
  server_url: "https://www.dati.gov.it/opendata",
  tag_query: "salute",
  limit: 25
})

搜索群组（自然语言：“查找与环境相关的群组”）

ckan_group_search({
  server_url: "https://www.dati.gov.it/opendata",
  pattern: "ambiente"
})

DataStore 查询（自然语言：“按地区和年份筛选表格数据”）

什么是 DataStore？ CKAN DataStore 是一个可选扩展，可将表格资源（CSV、Excel）导入可查询的数据库。它支持直接对数据进行筛选、排序和字段选择，无需下载文件。并非所有门户都启用了该功能；即使门户支持，也并非所有数据集都会使用它。检查资源上的 datastore_active: true，即可确认是否可用。

// Ordinanze viabili del Comune di Messina — resource with datastore_active: true
ckan_datastore_search({
  server_url: "https://dati.comune.messina.it",
  resource_id: "17301b8b-2a5b-425f-80b0-5b75bb1793e9",
  filters: { "tipo": "lavori" },
  sort: "data_pubblicazione desc",
  limit: 10
})

👏 特别感谢 Comune di Messina 和所有启用了 DataStore 扩展的公共管理机构：这样做让他们的数据更易于查询和探索，也能通过此类 AI 工具进行操作。

DataStore SQL 查询（自然语言：“按类型统计道路命令数量”）

// Count ordinanze viabili by tipo — Comune di Messina
ckan_datastore_search_sql({
  server_url: "https://dati.comune.messina.it",
  sql: "SELECT tipo, COUNT(*) AS total FROM \"17301b8b-2a5b-425f-80b0-5b75bb1793e9\" GROUP BY tipo ORDER BY total DESC LIMIT 5"
})

---

🧠 让多步查询更智能的 AI 技能

MCP 服务提供原始工具，而技能则教会你的 AI 助手如何智能地使用这些工具。

开箱即用的 AI 助手只了解每个工具的单独用途。技能增加了更高层次的推理能力：针对特定国家应查询哪个门户网站、门户网站无法访问时该怎么办、如何回退到欧洲开放数据门户，以及如何构造能够真正返回结果的查询。

技能新增的功能：

• 国家路由 — 自动识别某个国家最权威的 CKAN 门户网站（国家级 > 区域级 > 本地级）
• 回退链 — 如果门户网站无法访问或返回 0 条结果，则尝试其他选项；对于欧洲国家，还会使用正确的国家筛选条件回退到 data.europa.eu
• 查询构造 — 双语查询、解析器选择、fq 语法、通配符处理
• 正确的 API 调用模式 — 欧洲门户网站（data.europa.eu）需要特定的 facets+facetOperator+facetGroupOperator 参数，但文档中未说明这些参数，且很容易用错；技能会正确设置这些参数

技能支持的示例：

"Find road accident data in Portugal"
→ ckan_find_portals(country="Portugal")          # finds 3 regional portals
→ ckan_package_search on each → 0 results
→ [tells user] "No results on Portuguese CKAN portals. Trying data.europa.eu..."
→ curl "https://data.europa.eu/api/hub/search/search?q=acidentes+rodoviarios
         &facetOperator=AND&facetGroupOperator=AND&facets={"country":["pt"]}"
→ 157 datasets found — reported with source and filter details

"Find French open data about energy"
→ [knows data.gouv.fr is NOT CKAN — redirects to data.europa.eu]
→ curl "...?q=energie+energy&facets={"country":["fr"]}..."
→ Results filtered strictly to France

安装技能

技能文件夹位于此仓库的 skills/ckan-mcp/ 中，并已列入 skills.sh。使用 Skills CLI 安装：

# Install globally (available in all your projects)
npx skills add -g ondata/ckan-mcp-server --skill ckan-mcp

# Or for a single project (run from your project folder)
npx skills add ondata/ckan-mcp-server --skill ckan-mcp

---

🌍 支持的 CKAN 门户网站

以下是部分受支持的门户网站：

• 🇮🇹 https://www.dati.gov.it/opendata - 意大利国家开放数据门户（CKAN 2.10.3）
• 🇨🇦 https://open.canada.ca/data - 加拿大开放政府（CKAN 2.10.8）
• 🇦🇺 https://data.gov.au - 澳大利亚政府开放数据（CKAN 2.11.4）
• 🇬🇧 https://data.gov.uk - 英国开放数据
• 以及全球许多其他门户网站

catalog.data.gov 已不再使用 CKAN。 Data.gov 于 2025 年更换了目录，改用不同的 API（详情）；现在调用该站点时会说明这一点，而不是只返回一个 404 错误。

发现全球 CKAN 门户网站

Datashades.info/portals 维护着一个实时名录，收录了全球约 950 个 CKAN 门户网站，并提供版本、插件、数据集数量和地理坐标等元数据。感谢 Sara Petti 告知我们这个名录。

ckan_find_portals 工具可直接查询此名录。你可以按国家、语言、最低数据集数量或 DataStore 可用性筛选：

ckan_find_portals({ country: "Italy", has_datastore: true, limit: 5 })
ckan_find_portals({ language: "fr", min_datasets: 500 })
ckan_find_portals({ query: "transport" })

门户网站数据也可通过公开 JSON API 获取，无需身份验证：

端点	说明
GET https://datashades.info/api/portal/list	门户网站完整列表，包含 CKAN 版本、插件、数据集/资源/组织数量以及国家坐标
GET https://datashades.info/api/portal/stats	所有受监控门户网站的汇总统计数据
GET https://datashades.info/api/portal/historical/stats	受监控门户网站的历史趋势数据

---

🔍 高级 Solr 查询

CKAN 默认使用 Apache Solr 作为搜索引擎。了解 Solr 语法可充分发挥数据集搜索的能力，从简单关键词到复杂布尔表达式、模糊匹配、邻近搜索和日期计算。

基本语法

# Basic search
q: "popolazione"

# Field search
q: "title:popolazione"
q: "notes:sanità"

# Boolean operators
q: "popolazione AND sicilia"
q: "popolazione OR abitanti"
q: "popolazione NOT censimento"

# Filters (fq) — single value
fq: "organization:comune-palermo"
fq: "tags:sanità"
fq: "res_format:CSV"

# Filters (fq) — OR on same field: use field:(val1 OR val2)
fq: "res_format:(CSV OR JSON)"
fq: "organization:(comune-palermo OR comune-roma)"

# ⚠️ Wrong OR syntax — silently ignored, returns entire catalog:
# fq: "res_format:CSV OR res_format:JSON"   ← DO NOT USE

# Filters on CKAN extras fields — use extras_ prefix
fq: "extras_hvd_category:\"http://data.europa.eu/bna/c_ac64a52d\""
fq: "extras_hvd_category:(\"http://data.europa.eu/bna/c_ac64a52d\" OR \"http://data.europa.eu/bna/c_dd313021\")"

# Wildcard
q: "popolaz*"

# Date range
fq: "metadata_modified:[2023-01-01T00:00:00Z TO *]"

高级查询示例

以下真实示例展示了在意大利开放数据门户（dati.gov.it）上测试过的强大 Solr 查询组合：

1. 模糊搜索 + 日期运算 + 加权（自然语言：“查找过去 6 个月内修改的医疗保健数据集”）

查找医疗保健数据集（容忍拼写错误），这些数据集在过去 6 个月内修改，并优先显示标题匹配项：

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "(title:sanità~2^3 OR title:salute~2^3 OR notes:sanità~1) AND metadata_modified:[NOW-6MONTHS TO *]",
  sort: "score desc, metadata_modified desc",
  rows: 30
})

使用的技术：

• sanità~2 - 模糊搜索，编辑距离为 2（可匹配“sanita”、“sanitá”及轻微拼写错误）
• ^3 - 标题匹配项的相关性评分权重提高 3 倍
• NOW-6MONTHS - 用于滚动时间窗口的动态日期运算
• 结合多个字段搜索的布尔逻辑

结果：949 个数据集，包括医院部门、医疗保健组织和医疗服务

2. 邻近搜索 + 复杂布尔逻辑（自然语言：“查找排除水相关内容的空气污染数据集”）

查找包含相邻词语“inquinamento”和“aria”（空气污染）的环境数据集，同时排除与水相关的数据集：

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "(notes:\"inquinamento aria\"~5 OR title:\"qualità aria\"~3) AND NOT (title:acqua OR title:mare)",
  facet_field: ["organization", "res_format"],
  rows: 25
})

使用的技术：

• "inquinamento aria"~5 - 邻近搜索（词语间隔不超过 5 个位置）
• ~3 - 标题匹配使用更严格的邻近条件
• NOT (title:acqua OR title:mare) - 排除水／海洋相关数据集
• 使用分面进行统计细分

结果：305 个数据集

3. 通配符 + 字段存在性 + 日期运算（自然语言：“查找上个月发布且具有任意格式的地区数据集”）

查找上个月发布且至少声明了一种资源格式的地区数据集：

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "organization:regione* AND metadata_created:[NOW-1MONTH TO *] AND res_format:*",
  sort: "metadata_modified desc",
  facet_field: ["organization"],
  rows: 10
})

使用的技术：

• regione* - 使用通配符匹配所有地区组织
• res_format:* - 检查字段是否存在（至少声明了一种资源格式）
• NOW-1MONTH - 滚动 30 天时间窗口

结果：293 个数据集

4. 明确日期范围 + 分面（自然语言：“查找 2025 年更新的意大利劳动部数据集”）

查找意大利劳动部在 2025 年期间修改的数据集，并按格式和标签进行分面：

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "organization:ministero-del-lavoro AND metadata_modified:[2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]",
  sort: "metadata_modified desc",
  facet_field: ["res_format", "tags"],
  rows: 10
})

使用的技术：

• [2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z] - 明确指定日期范围（全年）
• organization:ministero-del-lavoro - 按特定组织筛选
• 使用多个分面细分格式和主题

结果：83 个数据集

Solr 查询语法参考

布尔运算符：AND、OR、NOT、+required、-excluded 通配符：*（多个字符）、?（单个字符）——注意：不支持左侧截断 模糊搜索：~N（编辑距离），例如 health~2 邻近搜索："phrase"~N（词语间隔不超过 N 个位置） 加权：^N（相关性倍数），例如 title:water^2 范围：

• 包含端点：[a TO b]，例如 num_resources:[5 TO 10]
• 不包含端点：{a TO b}，例如 num_resources:{0 TO 100}
• 无上限范围：[2024-01-01T00:00:00Z TO *]

日期运算：NOW、NOW-1YEAR、NOW-6MONTHS、NOW-7DAYS、NOW/DAY 字段存在性：field:*（字段存在）、NOT field:*（字段缺失）

---

📅 了解日期字段

CKAN 门户可以是源目录（由组织直接发布数据），也可以是收割聚合器（从许多其他门户收集数据）。在按日期筛选时，这一区别非常重要。

字段	在源门户中的含义	在聚合器中的含义
issued	发布者发布数据集的时间	发布者发布数据集的时间
metadata_created	记录首次创建的时间	记录首次被收割的时间
metadata_modified	记录最后更新的时间	记录最后一次重新收割的时间

在 dati.gov.it 这样的聚合器上，每次门户重新收割时，metadata_modified 都会更新——即使数据集内容没有变化。因此，它不适合用于查找“最近更新的内容”。

示例——dati.gov.it（聚合器）上同一数据集的三个不同时间戳：

{
  "issued": "2024-12-10",
  "metadata_created": "2024-12-16",
  "metadata_modified": "2026-02-28"
}

metadata_modified 显示为 2026 年 2 月，只是因为门户当时重新收割了数据——并非数据发生了变化。

在 dati.gov.it 上，哪些日期字段可用于筛选？

这三个字段都已建立 Solr 索引，可用于查询：

字段	已建立 Solr 索引	查询返回的内容
issued	✅	按发布者发布日期查找数据集——含义最明确，但约 14% 的数据集没有此字段
metadata_created	✅	按数据集首次在 dati.gov.it 上被收割的日期查找数据集
metadata_modified	✅	按数据集最后一次重新收割的日期查找数据集——结果往往杂乱

查询示例（dati.gov.it）：

# Datasets about road accidents published by the original source in 2025
ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "incidenti stradali",
  fq: "issued:[2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]"
})
// → ~121 results (only datasets where publisher filled in `issued`)

# Datasets first appearing on dati.gov.it in 2025
ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "incidenti stradali",
  fq: "metadata_created:[2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]"
})
// → ~164 results (includes older datasets harvested for the first time in 2025)

关于 issued 覆盖率的说明：dati.gov.it 上 69,000 多个数据集中，约有 59,700 个填有 issued。基于 issued 的查询准确但不完整——没有此字段的数据集会被静默排除。查询内容日期时优先使用 issued；只有在需要回答“数据集何时出现在门户上”时，才将 metadata_created 用作备用字段。

建议：使用 issued 按发布日期查找数据集。使用 metadata_created 查找近期出现在门户上的数据集。

---

👩‍💻 开发者参考

项目结构

ckan-mcp-server/
├── src/
│   ├── index.ts            # Entry point
│   ├── server.ts           # MCP server setup
│   ├── worker.ts           # Cloudflare Workers entry
│   ├── types.ts            # Types & schemas
│   ├── utils/
│   │   ├── http.ts         # CKAN API client
│   │   ├── formatting.ts   # Output formatting
│   │   └── url-generator.ts
│   ├── tools/
│   │   ├── package.ts      # Package search/show
│   │   ├── organization.ts # Organization tools
│   │   ├── datastore.ts    # DataStore queries
│   │   ├── status.ts       # Server status
│   │   ├── tag.ts          # Tag tools
│   │   └── group.ts        # Group tools
│   ├── resources/          # MCP Resource Templates
│   │   ├── index.ts
│   │   ├── uri.ts
│   │   ├── dataset.ts
│   │   ├── resource.ts
│   │   └── organization.ts
│   ├── prompts/            # MCP Guided Prompts
│   │   ├── index.ts
│   │   ├── theme.ts
│   │   ├── organization.ts
│   │   ├── format.ts
│   │   ├── recent.ts
│   │   └── dataset-analysis.ts
│   └── transport/
│       ├── stdio.ts
│       └── http.ts
├── tests/                  # Test suite
├── dist/                   # Compiled output (generated)
├── package.json
└── README.md

构建与测试

# Build (esbuild, ~4ms)
npm run build

# Watch mode
npm run watch

# Run all tests
npm test

# Watch mode for tests
npm run test:watch

# Coverage report
npm run test:coverage

使用 MCP Inspector 探索

MCP Inspector 可让你在网页 UI 中浏览工具、交互式测试调用并调试响应：

npm install -g @modelcontextprotocol/inspector
npm run build
npx @modelcontextprotocol/inspector node dist/index.js

打开地址 http://localhost:5173。

安全性：HTTP 传输需要域名允许列表

HTTP 传输（TRANSPORT=http）未经身份验证：任何能访问 POST /mcp 的客户端都可以通过它发送请求。自 v0.4.109 起，它默认绑定到 127.0.0.1 （环回地址）并启用 DNS 重绑定防护，因此不会暴露在局域网中，且会拒绝跨源浏览器请求。为防止 SSRF 滥用（例如调用方将 server_url 指向内部主机或云元数据），还会在未设置域名允许列表时拒绝启动：

变量	作用
CKAN_ALLOWED_DOMAINS	服务器可以查询的主机名允许列表，以逗号分隔（默认拒绝）。启动 HTTP 传输时必须设置。必须与主机名完全匹配，不支持通配符或子域名。每次重定向跳转也会进行检查：如果门户重定向到其他主机，也必须将该主机列入列表。示例：CKAN_ALLOWED_DOMAINS="www.dati.gov.it,dati.comune.messina.it"
CKAN_HTTP_ALLOW_ALL=true	明确选择不启用允许列表：启动 HTTP 传输时不使用允许列表（会记录安全警告）。不建议在网络对外开放时使用。
CKAN_HTTP_HOST	要绑定的接口（默认值为 127.0.0.1）。设置为 0.0.0.0 可对外开放，最好置于需要身份验证的反向代理之后。
CKAN_HTTP_ALLOWED_HOSTS	DNS 重绑定防护接受的额外 Host 标头值，以逗号分隔。绑定到环回地址以外的接口时，请添加你的公网主机名。
CKAN_HTTP_ALLOWED_ORIGINS	浏览器客户端允许的 Origin 标头值，以逗号分隔。

默认的 stdio 传输不受影响——它仍保持开放，因此你可以在本地查询任何门户。无论是否设置允许列表，所有请求也都会根据私有／内部 IP 地址范围进行验证，包括解析为内部地址的主机名（基于 DNS 的 SSRF，该问题已在 v0.4.108 修复）。官方 Cloudflare Worker 由平台提供沙箱隔离，因此不需要此设置。

手动测试 HTTP

# Start server (HTTP needs an allowlist — see "Security" above)
CKAN_ALLOWED_DOMAINS="www.dati.gov.it" TRANSPORT=http PORT=3001 node dist/index.js

# List available tools
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","method":"tools/call",
    "params":{"name":"ckan_package_search","arguments":{"server_url":"https://www.dati.gov.it/opendata","q":"ambiente","rows":3}},
    "id":1
  }' | jq -r '.result.content[0].text'

门户视图 URL 模板

有些 CKAN 门户会使用非标准网页 URL 来查看数据集或组织。为支持这些情况，本项目附带 src/portals.json，其中将已知的门户 API URL（及其别名）映射到自定义视图 URL 模板。

生成数据集或组织的视图链接时，服务器会：

• 将 server_url 与 src/portals.json 中的 api_url 和 api_url_aliases 进行匹配
• 在可用时使用门户专属的 dataset_view_url / organization_view_url 模板
• 回退到通用默认值（{server_url}/dataset/{name} 和 {server_url}/organization/{name}）

故障排除

意大利门户 URL 错误 — 请使用 https://www.dati.gov.it/opendata（而不是 https://dati.gov.it）。

连接错误

Error: Server not found: https://example.gov

请确认 URL 可访问，并使用 ckan_status_show 确认门户有响应。

没有结果 — 扩大查询范围，或使用分面检查可用内容：

ckan_package_search({
  server_url: "https://www.dati.gov.it/opendata",
  q: "*:*",
  facet_field: ["tags", "organization"],
  rows: 0
})

找不到结果时，LLM 使用外部数据 — 工具未返回结果时，有些 LLM（例如 ChatGPT）可能会在不作提示的情况下，使用训练数据中的信息补充答案。这是已知的 LLM 行为，并非服务器问题。为避免这种情况，请在系统提示词中要求模型只使用 MCP 工具返回的数据，不依赖外部来源。

---

🆘 支持

如有问题或疑问，请在 GitHub 上提交议题。

---

隐私政策

此服务器不会收集个人数据。它是只读且无状态的——查询会直接转发到你指定的公共 CKAN API，不会存储或记录任何数据。

请参阅完整的隐私政策。

---

相关工具

• opensituas — 通过命令行查看意大利各领土单位的代码和历史记录，是关联任何 ISTAT 数据集的键。
• opensdmx — 来自 Eurostat、ISTAT、OECD 及其他 SDMX 提供方的官方统计数据——没有幻觉，只有已发布的数据。
• ISTAT MCP Server — 通过 MCP 协议，直接在 AI 助手中获取意大利统计数据。

---

🔗 有用链接

• CKAN — 大多数公共开放数据门户背后的开源平台
• CKAN API Documentation — CKAN API v3 完整参考
• DCAT Vocabulary (W3C) — CKAN 门户用于描述数据集的元数据标准
• MCP Protocol — Model Context Protocol 规范

---

由 onData 用 ❤️ 为开放数据社区打造