MCP服务器

Security: HTTP transport requires a domain allowlist

The HTTP transport (TRANSPORT=http) is network-exposed and unauthenticated: any client that reaches POST /mcp can drive requests through it. To prevent SSRF abuse (e.g. a caller pointing server_url at internal hosts or cloud metadata), the HTTP transport refuses to start unless you set a domain allowlist:

The default stdio transport is unaffected — it stays open so you can query any portal locally. Regardless of allowlist, all requests are also validated against private/internal IP ranges, including hostnames that resolve to internal addresses (DNS-based SSRF, fixed in v0.4.108). The official Cloudflare Worker is sandboxed by the platform and does not require this setting.

Option 1 — Install via npm

The quickest way. Install the package globally and it's immediately available as a command:

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

The server will be available as ckan-mcp-server, or you can run it without installing via:

npx @aborruso/ckan-mcp-server@latest

Option 2 — Clone and build

For development or if you want to run the latest unreleased code:

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

Option 3 — Docker

Thanks to @piersoft, you can also run the server via Docker:

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

The MCP server will be available at http://localhost:3000/mcp. See docker/README.md for full details, including how to connect Claude Desktop to the container.

---

Install the skill

The skill folder lives at skills/ckan-mcp/ in this repository and is listed on skills.sh. Use the Skills CLI to install it:

```bash

Install globally (available in all your projects)

npx skills add -g ondata/ckan-mcp-server --skill ckan-mcp

Build & Test

```bash

Build (esbuild, ~4ms)

npm run build

💡 Usage Examples

Advanced Query Examples

These real-world examples demonstrate powerful Solr query combinations tested on the Italian open data portal (dati.gov.it):

1. Fuzzy Search + Date Math + Boosting (natural language: "find healthcare datasets modified in last 6 months")

Find healthcare datasets (tolerating spelling errors) modified in the last 6 months, prioritizing title matches:

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
})

Techniques used:

• sanità~2 - Fuzzy search with edit distance 2 (finds "sanita", "sanitá", minor typos)
• ^3 - Boosts title matches 3x higher in relevance scoring
• NOW-6MONTHS - Dynamic date math for rolling time windows
• Combined boolean logic with multiple field searches

Results: 949 datasets including hospital units, healthcare organizations, medical services

2. Proximity Search + Complex Boolean (natural language: "find air pollution datasets excluding water")

Environmental datasets where "inquinamento" and "aria" (air pollution) appear close together, excluding water-related datasets:

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
})

Techniques used:

• "inquinamento aria"~5 - Proximity search (words within 5 positions)
• ~3 - Tighter proximity for title matches
• NOT (title:acqua OR title:mare) - Exclude water/sea datasets
• Faceting for statistical breakdown

Results: 305 datasets

3. Wildcard + Field Existence + Date Math (natural language: "regional datasets with any format from last month")

Regional datasets published in the last month that have at least one resource format declared:

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
})

Techniques used:

• regione* - Wildcard matches all regional organizations
• res_format:* - Field existence check (has at least one resource format declared)
• NOW-1MONTH - Rolling 30-day window

Results: 293 datasets

4. Explicit Date Range + Facets (natural language: "Ministry of Labour datasets updated in 2025")

Datasets from the Italian Ministry of Labour modified during 2025, with facets by format and tags:

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
})

Techniques used:

• [2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z] - Explicit date range (full year)
• organization:ministero-del-lavoro - Filter by specific organization
• Multiple facets for format and topic breakdown

Results: 83 datasets

Search groups (natural language: "find groups about environment")

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

Solr Query Syntax Reference

Boolean Operators: AND, OR, NOT, +required, -excluded Wildcards: * (multiple chars), ? (single char) - Note: left truncation not supported Fuzzy: ~N (edit distance), e.g., health~2 Proximity: "phrase"~N (words within N positions) Boosting: ^N (relevance multiplier), e.g., title:water^2 Ranges:

• Inclusive: [a TO b], e.g., num_resources:[5 TO 10]
• Exclusive: {a TO b}, e.g., num_resources:{0 TO 100}
• Open-ended: [2024-01-01T00:00:00Z TO *]

Date Math: NOW, NOW-1YEAR, NOW-6MONTHS, NOW-7DAYS, NOW/DAY Field Existence: field:* (field exists), NOT field:* (field missing)

---

👩‍💻 Developer Reference

VS Code

Add to your User Settings or .vscode/settings.json:

Using the hosted endpoint (no install):

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

Using local installation:

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

Troubleshooting

Wrong URL for Italian portal — use https://www.dati.gov.it/opendata (not https://dati.gov.it).

Connection error

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

Verify the URL is reachable and use ckan_status_show to confirm the portal is responding.

No results — broaden your query or check what's available with facets:

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

LLM uses external data when no results are found — when a tool returns no results, some LLMs (e.g. ChatGPT) may supplement the answer with information from their training data without warning. This is a known LLM behavior, not a server issue. To avoid it, instruct the model in your system prompt to only use data returned by the MCP tools and not rely on external sources.

---