mcp-server-qlever

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

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
examples/gnd		examples/gnd
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.allinone.yml		docker-compose.allinone.yml
docker-compose.gnd.yml		docker-compose.gnd.yml
docker-compose.test.yml		docker-compose.test.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

mcp-server-qlever

Features

Quick Start

A) You already have a QLever endpoint

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

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

Installation

npx (no install)

npm (global)

Docker

From source

Configuration

Claude Code (CLI)

Claude Code (VS Code / Cursor)

Manual configuration (any MCP client)

Multiple endpoints

Tool Reference

Prompts

QLever-Specific Features

Security

Environment Variables

CLI Usage

Running QLever with Docker

Preconfigured dataset

Custom RDF data

Examples

Development

Testing

Building the Docker image

License

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages