MCP Server Qlever

mcp服务器qlever

](https://www.npmjs.com/package/mcp-server-qlever)  

A. 模型上下文协议 （MCP）服务器 QLever SPARQL引擎。连接克劳德代码或 任何兼容MCP的客户端到由QLever支持的知识图。

特性

• 使用格式化文本或原始JSON输出执行SPARQL查询
• 通过列出按频率排序的谓词来探索数据集模式
• 按IRI查找具有传出和传入三元组的实体
• 使用全文匹配按标签搜索实体
• 通过QLever实现上下文敏感的SPARQL自动补全 /ac 端点
• 不执行查询计划分析
• 通过QLever的原生空间连接进行地理搜索（半径/边界框）
• SPARQL 1.1更新，包括模拟运行预览和安全防护
• 输入消毒：IRI验证和SPARQL注射预防
• 适用于任何QLever实例（本地Docker、自托管或公共）

快速开始

选择您的场景：

A） 您已经拥有QLever端点

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

完成。克劳德现在可以查询你的知识图谱了。

B） 你想要一切从头开始（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

这将以一个小的测试数据集启动QLever，并将MCP服务器连接到它。

C） 你想要真实世界的数据（例如德国国家图书馆）

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

首次运行会自动下载并索引GND Werk权威数据（约90 MB，约3.5 M三元组）。 看 examples/gnd/ 了解详情。

安装

有几种方法可以安装和运行服务器。选择适合您设置的选项。

npx（不安装）

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

npm（全局）

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

码头工人

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

使用 --network=host 在Linux上访问本地主机上的QLever实例：

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

环境变量也起作用：

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

来源

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

要求： Node.js 18+（所有方法）或Docker/Podman（Docker方法）。

配置

克劳德代码（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

使用Docker镜像而不是npx：

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

验证：

claude mcp list

克劳德代码（VS代码/光标）

编辑 .vscode/settings.json:

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

或者使用Docker：

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

手动配置（任何MCP客户端）

添加 ~/.claude.json 或 .claude/settings.json:

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

通过env使用访问令牌：

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

多个端点

以不同的名称注册多个QLever实例：

{
  "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"]
    }
  }
}

工具参考

提示

QLever特定功能

该服务器超越了一般的SPARQL访问，暴露了QLever的独特功能：

• 上下文相关的自动补全 --The sparql_autocomplete 该工具使用QLever的 /ac endpoint根据索引中实际存在的内容建议完成。
• 查询计划分析 --The analyze_query 该工具返回QLever的内部查询计划，其中包含估计的结果大小，有助于在执行前预测性能。
• 全文搜索 --The search_fulltext 该工具使用QLever的SPARQL+Text扩展来查找与文本语料库中的关键字同时出现的实体。
• 空间查询 --The spatial_query 该工具使用QLever的本地空间连接进行高效的地理搜索。
• 安全SPARQL更新 --The sparql_update 该工具包括干运行预览、破坏性操作检测(DROP/CLEAR ALL|DEFAULT|NAMED)，以及访问令牌强制执行。

安全

在插入SPARQL之前，所有用户控制的输入都经过消毒：

• 字符串常量 逃脱了 \ " \n \r \t 防止SPARQL注入
• 虹膜 根据RFC 3987进行验证（拒绝 <>"{}|\^ ` `` 和控制字符）
• 谓词 使用严格的正则表达式匹配前缀名称或安全的完整IRI进行验证
• SPARQL更新 需要显式访问令牌并标记破坏性操作

环境变量

CLI标志优先于环境变量。

命令行用法

mcp-server-qlever --endpoint  [options]

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

使用Docker运行QLever

QLever需要一个两步过程：从RDF数据构建索引，然后为其提供服务。

预配置数据集

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

自定义RDF数据

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

请参阅 QLever文档 有关数据集的详细信息 配置、索引设置和性能调优。

例子

这 examples/ 目录包含特定数据集的现成设置：

每个示例包括 docker-compose.yml 下载、转换和索引数据 第一次运行时自动。后续启动是即时的（索引保存在Docker卷中）。

想添加自己的数据集吗？复制任何示例目录并调整数据源URL。

发展

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

测试

该项目有336个测试，分为三层：

# 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)

构建Docker镜像

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

许可证

麻省理工学院

链接

• QLever --高性能SPARQL发动机（弗莱堡大学）
• QLever文档 --安装指南和API参考
• 模型上下文协议 --MCP规范
• --Bug报告和功能请求