kapsarc-mcp-server 0.1.0

MCP server for the KAPSARC Data Portal — search, query, export, and visualize energy/economic datasets

KAPSARC Data Portal MCP Server

An MCP server that connects LLMs to the KAPSARC Data Portal — search, query, export, and visualize energy and economic datasets via the Opendatasoft Explore API v2.1.

Tools

Data Tools

Tool	Description
search_datasets	Free-text search of KAPSARC datasets
get_dataset	Full metadata and field definitions for a dataset
get_records	Query records with ODSQL filters
get_record	Retrieve a single record by ID
get_dataset_facets	Categorical field values and counts
get_catalog_facets	Portal-wide themes, keywords, publishers
export_dataset	Export without 100-record limit (JSON/CSV)
get_dataset_attachments	List documentation/file attachments
export_catalog	Bulk export all dataset metadata
list_export_formats	Check available export formats

Visualization Tools

Tool	Description
visualize_dataset	Fetch data and render a branded chart image
visualize_data	Render a chart from pre-fetched records (no API call)
visualize_comparison	Multi-series comparison charts (e.g. country vs country)

All charts are returned as PNG images with official KAPSARC branding — logo, color palette, and source attribution. Chart types are auto-detected from data shape, or can be explicitly set to: bar, hbar, line, pie, or scatter.

Example Charts

Bar Chart — Top Oil Producers

Line Chart — Time Series

Pie Chart — Energy Mix

Multi-Line — Production Comparison

Scatter Plot — GDP vs Energy

Horizontal Bar — Energy by Sector

Electricity Prices

Renewable Energy Capacity

GCC Power Generation Mix

Multi-Bar — CO2 Emissions

Solar Irradiance vs Capacity Factor

Renewable Share of Electricity

Hydrogen Production Costs

Brent Crude Oil Price

Saudi Arabia GDP Composition

Installation

Quick Start

uvx kapsarc-mcp-server

Or install with pip:

pip install kapsarc-mcp-server
kapsarc-mcp-server

Claude Code

claude mcp add kapsarc-data -- uvx kapsarc-mcp-server

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "kapsarc-data": {
      "command": "uvx",
      "args": ["kapsarc-mcp-server"]
    }
  }
}

Development

git clone https://github.com/MHDhazmi/kapsarc-mcp-server.git
cd kapsarc-mcp-server
uv sync
uv run kapsarc-mcp-server

Configuration

Set the KAPSARC_API_KEY environment variable to authenticate with the KAPSARC API. This is optional — most datasets are publicly accessible without a key.

export KAPSARC_API_KEY="your-api-key"

Development

# Unit tests (no network needed)
uv run pytest tests/test_charts.py -v

# Integration tests (hits live KAPSARC API)
uv run pytest tests/test_main.py -v

# Regenerate example chart images
uv run python examples/generate_examples.py

License

MIT