ckan

This MCP server exposes a set of tools that let MCP-compatible clients browse and interact with CKAN data portals via the Model Context Protocol. It provides endpoints for listing and inspecting packages (datasets), organizations, data related resources, and metadata, as well as search and datastore capabilities. Clients can issue structured tool invocations through MCP to query CKAN data, retrieve package details, or explore organizational information, all through the standard MCP JSON round-trips over standard input/output.

To use it, start the server (for example with python mcp_ckan_server.py after configuring CKAN_URL and optional CKAN_API_KEY). Then call the provided tools by name, passing appropriate arguments as shown in the Examples section. Tools cover Packages/Datasets (ckan_package_list, ckan_package_show, ckan_package_search), Organizations (ckan_organization_list, ckan_organization_show), DataStore (ckan_datastore_search), Groups/Tags (ckan_group_list, ckan_tag_list), Resources (ckan_resource_show), and System endpoints (ckan_site_read, ckan_status_show). You can also query API documentation and server configuration resources via the CKAN API reference and the server's config endpoints.

Common usage patterns include listing datasets, filtering by search terms, inspecting organization details, and retrieving specific resource metadata to feed downstream AI workflows.

Prerequisites:

• Python 3.13 or higher
• pip (Python package installer)
• Access to the CKAN instance you intend to query

Installation steps:

1. Clone the repository or download the MCP server files.
2. Create and activate a Python environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows

3. Install required dependencies:

pip install -r requirements.txt

4. Configure environment variables (CKAN_URL and optional CKAN_API_KEY):

export CKAN_URL="https://demo.ckan.org"
export CKAN_API_KEY="your-api-key-here"  # optional

(Alternatively, copy .env.example to .env and populate it.) 5) Run the server directly to test:

python mcp_ckan_server.py

6. If you plan to run via Docker, ensure the Dockerfile is present and build the image, then run it with the required environment variables:

docker build -t ckan-mcp-server .
docker run -e CKAN_URL="https://demo.ckan.org" -e CKAN_API_KEY="your-key" ckan-mcp-server

Environment variables:

• CKAN_URL is required for the server to connect to a CKAN instance.
• CKAN_API_KEY is optional but recommended for write operations against CKAN.

Common issues:

• Ensure CKAN_URL is reachable from where the MCP server runs.
• If CKAN_API_KEY is invalid or missing for write operations, CKAN may reject requests; tests should use a public CKAN instance or a valid API key.
• When running via Docker, ensure network access to CKAN_URL is allowed and the container has internet access.

Configuration tips:

• You can store configuration in a .env file and load it at startup to simplify environment management.
• Use the CKAN API reference for constructing valid tool arguments, such as id, q, rows, and include_datasets when applicable.