ckan-mcp-server

[![npm version](https://img.shields.io/npm/v/@aborruso/ckan-mcp-server)](https://www.npmjs.com/package/@aborruso/ckan-mcp-server)
[![GitHub](https://img.shields.io/badge/github-ondata%2Fckan--mcp--server-blue?logo=github)](https://github.com/ondata/ckan-mcp-server)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ondata/ckan-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Newsletter](https://img.shields.io/badge/newsletter-ondata-FF6719?logo=substack)](https://ondata.substack.com/)
[![Greptile: The War on Bugs](https://www.greptile.com/badge.svg)](https://www.greptile.com/?utm_source=oss_badge&utm_medium=readme&utm_campaign=greptile_for_open_source)

# CKAN MCP Server

*Turn any (CKAN) open data portal into a conversation.*

**Give your AI assistant direct access to any CKAN open data portal — search datasets, explore organizations, query tabular data, and read metadata, all through natural language.**

CKAN is the open-source platform behind most public open data portals worldwide (Italy's dati.gov.it, the US data.gov, Canada's open.canada.ca, and many more). Navigating these portals usually requires knowing their structure, APIs, and search syntax. This MCP server removes that barrier: once connected, your AI tool can do it all for you.

**This is possible because of open standards and open source.** CKAN exposes a fully documented, public API. Metadata follows [DCAT](https://www.w3.org/TR/vocab-dcat/), an open W3C standard for describing datasets. Both are free to use, free to build on, and maintained by open communities. This server stands on that foundation.

**Who is this for?** Everyone. Journalists looking for data to verify a story. Researchers exploring public datasets. Public servants checking what data their administration publishes. Developers building data pipelines. No CKAN knowledge required.

> **Adopted by AgID** — This project has been [reused by AgID](https://github.com/agID/ckan-mcp-server), Italy's Agency for Digital Italy, as part of its effort to make public open data more accessible, immediate, and easier to consult through AI.

**Two ways to use it — pick the one that suits you:**

| | Option A: Install locally | Option B: No install |
|---|---|---|
| **How** | `npm install -g @aborruso/ckan-mcp-server` | Point your tool to the hosted HTTP endpoint |
| **Best for** | Runs on your machine, works with any local tool | Quick start, zero setup |
| **Request quota** | No shared quota | 100k requests/day shared quota |

Hosted endpoint: `https://ckan-mcp-server.andy-pr.workers.dev/mcp`

> **Recommendation**: Option B is a great way to get started and try things out without any setup. Once you're familiar with what the server can do, switching to Option A (local install) gives you unlimited usage with no shared quotas.

👉 Want to explore the codebase? The [**AI-generated DeepWiki**](https://deepwiki.com/ondata/ckan-mcp-server) is a great starting point.

**License**: MIT — see [LICENSE](LICENSE) for complete details. Third-party notices: [NOTICE.md](NOTICE.md).

![CKAN MCP Server demo](docs/guide/mcp_server_demo.gif)

---

## ⚖️ Limits

The local and hosted server use the same tool and output caps. The hosted endpoint also has the shared request quota shown above.

| Area | Default | Maximum or configuration |
|---|---:|---|
| Tool output | 50,000 characters | Fixed server-wide cap |
| `ckan_datastore_search` rows | 100 | 32,000 (`0` returns column names only) |
| `ckan_package_search` results per page | 10 | 1,000 |
| `ckan_find_relevant_datasets` results | 10 | 50 |
| Injected `sparql_query` rows | 25 | 1,000 when injected; a query that supplies its own `LIMIT` is not capped |
| `ckan_tag_list` results | 100 | 1,000 |
| `ckan_find_portals` results | 10 | 50 |
| HTTP response body | 32 MiB | `CKAN_MAX_RESPONSE_BYTES` for local Node.js deployments |
| Decompressed response body | 64 MiB | `CKAN_MAX_DECOMPRESSED_BYTES` for local Node.js deployments |

Text and Markdown responses that exceed the output cap are cut and include a truncation note. JSON responses stay parseable: the server reduces known result arrays and flags the response with `_truncated` and `_original_count`, and if a response still cannot fit it is replaced by a small object carrying `_truncated` and an explanatory `_error`. The same capped payload is sent on both channels, so a client reading `structuredContent` sees exactly what the text shows, truncation flags included. Use pagination or a narrower query when you need the complete result set.

---

## 🔌 Use it in your favorite tool

[ChatGPT](#chatgpt) | [Claude Desktop](#claude-desktop) | [Claude Code](#claude-code) | [Le Chat (Mistral)](#le-chat-mistral) | [Perplexity Pro](#perplexity-pro) | [Gemini CLI](#gemini-cli) | [VS Code](#vs-code) | [Codex CLI](#codex-cli)

This server works with any MCP-compatible client. The sections below cover some of the most popular ones — if your tool isn't listed, check its documentation for MCP configuration and use the same endpoint URL or command.

All examples below work with **both** the local installation and the hosted endpoint. Where both options differ, both are shown.

> **Using local installation?** You need to install the server first — see [Run locally](#run-locally).

### ChatGPT

> Requires a ChatGPT Plus, Team, or Enterprise plan.

1. Open the profile menu and go to **Settings → Apps → Advanced settings**
2. Enable **Developer mode**
3. Click **Create app** (top-right)
4. Fill in the form:
   - **Name:** CKAN MCP Server
   - **Description:** Search datasets on CKAN open data portals
   - **MCP Server URL:** `https://ckan-mcp-server.andy-pr.workers.dev/mcp`
   - **Authentication:** No Auth
   - Check the confirmation box, then click **Create**
5. In a new chat, click **+** → **More** and select **CKAN MCP Server**

> For a step-by-step walkthrough with screenshots, see the [full ChatGPT guide](https://github.com/ondata/ckan-mcp-server/blob/main/docs/guide/chatgpt/chatgpt_web.md).

### Claude Desktop

**Using the hosted endpoint (no install) — via connector UI:**

1. Open Claude Desktop and go to **Settings → Integrations**
2. Click **Add custom integration**
3. Fill in the details:
   - **Name:** CKAN MCP Server
   - **MCP Server URL:** `https://ckan-mcp-server.andy-pr.workers.dev/mcp`
4. Click **Add** to save
5. Open a new chat, click **+**, select **Integrations**, and enable **CKAN MCP Server**
6. When Claude asks to use a tool, click **Allow** (or **Always allow**)

> For a detailed walkthrough with screenshots, see the [full Claude guide](https://github.com/ondata/ckan-mcp-server/blob/main/docs/guide/claude/claude_web.md).

**Using the hosted endpoint (no install) — via config file:**

Configuration file location:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

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

**Using local installation:**

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

### Claude Code

**Using the hosted endpoint (no install):**

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

**Using local installation:**

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

> `--scope user` makes the server available globally across all your projects, not just the current one.

To add it only for a specific project, run from the project folder without the `--scope user` flag:

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

### Le Chat (Mistral)

1. In the left sidebar, click **Intelligence**, then select **Connectors**
2. Click **+ Add Connector**
3. Select the **Custom MCP Connector** tab and fill in the details:
   - **Name:** CKAN
   - **Connector Server:** `https://ckan-mcp-server.andy-pr.workers.dev/mcp`
4. Click **Connect** to save
5. Open a new chat, click **+**, then **Connectors**, and enable **CKAN**

> For a step-by-step walkthrough with screenshots, see the [full Le Chat guide](https://github.com/ondata/ckan-mcp-server/blob/main/docs/guide/mistral/mistral_web.md).

### Perplexity Pro

> Requires a Perplexity Pro account.

1. Click the "+" (Attach) icon in the message input bar and select **Connectors & sources**
2. Click **Connect external app**
3. Fill in the details:
   - **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. Check the confirmation box and click **Save**
5. In a new chat, click **+** → **Connectors & sources** and enable **ckan_mcp_server**

> For a step-by-step walkthrough with screenshots, see the [full Perplexity guide](https://github.com/ondata/ckan-mcp-server/blob/main/docs/guide/perplexity/perplexity.md).

### Gemini CLI

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

Or add manually to `~/.gemini/settings.json`:

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

### VS Code

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

**Using the hosted endpoint (no install):**

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

**Using local installation:**

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

### Codex CLI

Add to `~/.codex/config.toml`:

**Using the hosted endpoint (no install):**

```toml
[mcp_servers.ckan]