Qlever

npm version License: MIT MCP

A Model Context Protocol (MCP) server for the QLever SPARQL engine. Connect Claude Code or any MCP-compatible client to knowledge graphs powered by QLever.

Features

• Execute SPARQL queries with formatted text or raw JSON output
• Explore dataset schemas by listing predicates ordered by frequency
• Look up entities by IRI with outgoing and incoming triples
• Search for entities by label using full-text matching
• Context-sensitive SPARQL autocompletion via QLever's /ac endpoint
• Query plan analysis without execution
• Geographic search (radius / bounding box) via QLever's native spatial join
• SPARQL 1.1 Update with dry-run preview and safety guards
• Input sanitization: IRI validation and SPARQL injection prevention
• Works with any QLever instance (local Docker, self-hosted, or public)

Quick Start

Pick your scenario:

A) You already have a QLever endpoint

claude mcp add qlever -- npx -y mcp-server-qlever -e http://your-qlever:7019

Done. Claude can now query your knowledge graph.

B) You want everything from scratch (QLever + MCP)

docker compose -f docker-compose.allinone.yml up -d --wait
claude mcp add qlever -- npx -y mcp-server-qlever -e http://localhost:7019

This starts QLever with a small test dataset and connects the MCP server to it.

C) You want real-world data (e.g. German National Library)

cd examples/gnd
docker compose up -d --wait
claude mcp add gnd -- npx -y mcp-server-qlever -e http://localhost:7020

First run downloads and indexes the GND Werk authority data (~90 MB, ~3.5M triples) automatically. See examples/gnd/ for details.

Installation

There are several ways to install and run the server. Pick whichever fits your setup.

npx (no install)

npx mcp-server-qlever --endpoint http://localhost:7019

npm (global)

npm install -g mcp-server-qlever
mcp-server-qlever --endpoint http://localhost:7019

Docker

docker run --rm -i ghcr.io/xorwell/mcp-server-qlever:latest \
  --endpoint http://host.docker.internal:7019

Use --network=host on Linux to reach a QLever instance on localhost:

docker run --rm -i --network=host ghcr.io/xorwell/mcp-server-qlever:latest \
  --endpoint http://localhost:7019

Environment variables work too:

docker run --rm -i --network=host \
  -e QLEVER_ENDPOINT=http://localhost:7019 \
  -e QLEVER_ACCESS_TOKEN=my-token \
  ghcr.io/xorwell/mcp-server-qlever:latest

From source

git clone https://github.com/XORwell/mcp-server-qlever.git
cd mcp-server-qlever
npm install
npm run build
node dist/index.js --endpoint http://localhost:7019

Requirements: Node.js 18+ (all methods), or Docker/Podman (Docker method).

Configuration

Claude Code (CLI)

# Project-scoped
claude mcp add qlever -- npx -y mcp-server-qlever --endpoint http://localhost:7019

# User-scoped (all projects)
claude mcp add -s user qlever -- npx -y mcp-server-qlever --endpoint http://localhost:7019

Using the Docker image instead of npx:

claude mcp add qlever -- docker run --rm -i --network=host \
  ghcr.io/xorwell/mcp-server-qlever:latest --endpoint http://localhost:7019

Verify:

claude mcp list

Claude Code (VS Code / Cursor)

Edit .vscode/settings.json:

{
  "claude-code.mcpServers": {
    "qlever": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "--endpoint", "http://localhost:7019"]
    }
  }
}

Or with Docker:

{
  "claude-code.mcpServers": {
    "qlever": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "ghcr.io/xorwell/mcp-server-qlever:latest",
        "--endpoint", "http://localhost:7019"
      ]
    }
  }
}

Manual configuration (any MCP client)

Add to ~/.claude.json or .claude/settings.json:

{
  "mcpServers": {
    "qlever": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "--endpoint", "http://localhost:7019"]
    }
  }
}

With access token via env:

{
  "mcpServers": {
    "qlever": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "--endpoint", "http://localhost:7019"],
      "env": {
        "QLEVER_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Multiple endpoints

Register several QLever instances under different names:

{
  "mcpServers": {
    "qlever-wikidata": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "-e", "http://localhost:7019"]
    },
    "qlever-osm": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "-e", "http://localhost:7020"]
    },
    "qlever-dblp": {
      "command": "npx",
      "args": ["-y", "mcp-server-qlever", "-e", "http://localhost:7021"]
    }
  }
}

Tool Reference

Tool	Description	Key Parameters
sparql_query	Execute SPARQL and get formatted text results	query, timeout, max_rows
sparql_query_json	Execute SPARQL and get raw JSON response	query, timeout, max_rows
get_index_stats	Retrieve dataset metadata (triple count, predicates, etc.)	--
describe_entity	Look up all triples for an entity by IRI	iri, limit
search_entities	Full-text search for entities by label	search_term, label_predicate, limit
get_predicates	List available predicates ordered by frequency	limit, timeout
sparql_autocomplete	Context-sensitive autocompletion using QLever's /ac endpoint	partial_query, context, entity_name, limit
analyze_query	Get query execution plan without running the query	query
list_named_graphs	List all named graphs with triple counts	limit
search_fulltext	Search QLever's text index for entity-keyword co-occurrence	keywords, filter_type, limit
spatial_query	Geographic search (radius or bounding box) via spatial join	mode, lat, lon, radius_km / bbox params, limit
sparql_update	Execute SPARQL 1.1 Update (requires access token)	update, graph_uri, dry_run, confirm

Prompts

Prompt	Description
explore_dataset	Step-by-step workflow for discovering an unknown QLever dataset
safe_update_workflow	Validated workflow for SPARQL Update operations with dry-run preview

QLever-Specific Features

This server goes beyond generic SPARQL access by exposing QLever's unique capabilities:

• Context-sensitive autocompletion -- The sparql_autocomplete tool uses QLever's /ac endpoint to suggest completions based on what actually exists in the index.
• Query plan analysis -- The analyze_query tool returns QLever's internal query plan with estimated result sizes, helping predict performance before execution.
• Full-text search -- The search_fulltext tool uses QLever's SPARQL+Text extension to find entities co-occurring with keywords in the text corpus.
• Spatial queries -- The spatial_query tool uses QLever's native spatial join for efficient geographic searches.
• Safe SPARQL Update -- The sparql_update tool includes dry-run preview, destructive operation detection (DROP/CLEAR ALL|DEFAULT|NAMED), and access token enforcement.

Security

All user-controlled inputs are sanitized before interpolation into SPARQL:

• String literals are escaped for \ " \n \r \t to prevent SPARQL injection
• IRIs are validated against RFC 3987 (rejects <>"{}|\^ ` and control characters)
• Predicates are validated with a strict regex matching prefixed names or safe full IRIs
• SPARQL Update requires explicit access token and flags destructive operations

Environment Variables

Variable	Description	Default
QLEVER_ENDPOINT	QLever API URL (fallback if --endpoint not given)	--
QLEVER_ACCESS_TOKEN	Access token for privileged operations	--
QLEVER_TIMEOUT	Default query timeout (e.g. 30s, 2min)	30s

CLI flags take precedence over environment variables.

CLI Usage

mcp-server-qlever --endpoint <url> [options]

Options:
  -e, --endpoint <url>      QLever API endpoint URL (required)
  -t, --access-token <tok>  Access token for privileged operations
      --timeout <duration>   Default query timeout (default: 30s)
  -h, --help                Show help message
  -v, --version             Show version

Running QLever with Docker

QLever requires a two-step process: build an index from RDF data, then serve it.

Preconfigured dataset

docker run -it --name qlever-wikidata -p 7019:7019 adfreiburg/qlever:latest bash

# Inside the container:
qlever setup-config wikidata    # or: olympics, dblp, osm-planet, uniprot, ...
qlever get-data                 # downloads the dataset
qlever index                    # builds the index (may take minutes to hours)
qlever start                    # starts the SPARQL server on port 7019

Custom RDF data

docker run -it --name qlever-custom -p 7019:7019 \
  -v /path/to/your/data:/data \
  adfreiburg/qlever:latest bash

# Inside the container:
qlever-index -i /data/myindex -f /data/mydata.nt -F nt -s /data/settings.json
qlever-server -i /data/myindex -p 7019 -m 4GB

See the QLever documentation for details on dataset configuration, index settings, and performance tuning.

Examples

The examples/ directory contains ready-to-use setups for specific datasets:

Example	Dataset	Triples	Setup
examples/gnd/	GND Werk (Deutsche Nationalbibliothek)	~3.5M	cd examples/gnd && docker compose up

Each example includes a docker-compose.yml that downloads, converts, and indexes the data automatically on first run. Subsequent starts are instant (index persisted in Docker volume).

Want to add your own dataset? Copy any example directory and adjust the data source URL.

Development

git clone https://github.com/XORwell/mcp-server-qlever.git
cd mcp-server-qlever
npm install
npm run build

Testing

The project has 336 tests across three layers:

# Unit tests only (no Docker needed)
npm run test:unit

# Integration tests against real QLever (scientists dataset)
docker compose -f docker-compose.test.yml up -d --wait
npm run test:integration
docker compose -f docker-compose.test.yml down -v

# E2E tests over real MCP stdio transport (GND dataset, 390K triples)
# First, generate the test fixture from DNB open data:
pip install ijson
curl -o /tmp/gnd-werk.jsonld.gz https://data.dnb.de/opendata/authorities-gnd-werk_lds_20260217.jsonld.gz
python3 scripts/jsonld-to-nt.py -i /tmp/gnd-werk.jsonld.gz --limit 50000 > test/fixtures/gnd/gnd-werk-sample.nt
docker compose -f docker-compose.gnd.yml up -d --wait
npm run build
npm run test:e2e
docker compose -f docker-compose.gnd.yml down -v

# Everything at once
npm run test:ci       # unit + integration (scientists)
npm run test:ci:gnd   # all tests including E2E (GND)

Layer	Tests	What it covers
Unit	282	All tools, client, security (SPARQL injection, IRI validation, bounds, timeouts)
Integration	25	Real QLever queries against scientists and GND authority data
E2E	29	Real MCP server process over stdio, all 12 tools + 2 prompts against live QLever

Building the Docker image

docker build -t mcp-server-qlever:local .
docker run --rm mcp-server-qlever:local --help

License

MIT

Links

• QLever -- High-performance SPARQL engine (University of Freiburg)
• QLever Documentation -- Setup guides and API reference
• Model Context Protocol -- MCP specification
• GitHub Issues -- Bug reports and feature requests