sparql-mcp

A Model Context Protocol (MCP) server that lets any MCP-aware agent (Claude Desktop, Claude Code, Hermes Agent, Cursor, Continue, …) query SPARQL endpoints and explore RDF knowledge graphs.

Ships LINDAS-aware helpers out of the box but works against any SPARQL 1.1 endpoint — Wikidata, DBpedia, GraphDB, Fuseki, Stardog, Blazegraph, Virtuoso, AllegroGraph, Oxigraph, Amazon Neptune (SPARQL endpoint), etc.

Read-only by design — only SELECT, ASK, CONSTRUCT, and DESCRIBE forms are accepted. Update / Graph-Store-Protocol operations are blocked.

Features

• Generic SPARQL 1.1 query — SELECT / ASK / CONSTRUCT / DESCRIBE against any endpoint URL or built-in alias.
• Built-in endpoint aliases: lindas, wikidata, dbpedia, lov — plus any number of user-defined endpoints via TOML.
• LINDAS helpers: list cubes, describe cube components (dimensions / measures), list datasets and publishing agents — pre-baked queries so the LLM doesn't re-derive the schema on every call.
• Generic graph introspection: list classes, list most-used predicates (with optional sampling for large endpoints), list named graphs, sample instances of a class, expose known prefixes.
• Output formats: json (default), csv, tsv, markdown, toon (token-optimised compact format).
• Auth: basic / bearer / custom-header per endpoint, with secrets sourceable from environment variables.
• Optional rich extra — adds rdflib-backed parse_rdf, serialize_graph, and sparql_construct_to_graph tools.

Install

pip install sparql-mcp                # core
pip install "sparql-mcp[rich]"        # + rdflib for graph parsing / serialization

From source:

git clone https://github.com/rareba/sparql-mcp
cd sparql-mcp
uv venv && uv pip install -e ".[dev,rich]"

Wire it up

Claude Desktop / Claude Code

Add to your claude_desktop_config.json (or ~/.claude/mcp.json):

{
  "mcpServers": {
    "sparql": {
      "command": "sparql-mcp"
    }
  }
}

Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  sparql:
    command: /full/path/to/.venv/bin/sparql-mcp

Run directly

sparql-mcp                # stdio transport
python -m sparql_mcp      # equivalent

Example prompts

"List the five biggest LINDAS cubes."

"Describe the cube https://agriculture.ld.admin.ch/crops/agis/1/."

"Run this query on Wikidata: SELECT ?country ?pop WHERE { ?country wdt:P31 wd:Q6256; wdt:P1082 ?pop } ORDER BY DESC(?pop) LIMIT 10."

"What classes are defined in my local Fuseki?"

Tools

Tool	What it does
sparql_query_tool	Generic SPARQL query against any endpoint
list_endpoints_tool	List built-in + user endpoints (auth redacted)
describe_resource_tool	DESCRIBE <iri> on the chosen endpoint
list_classes_tool	Distinct rdf:type values
list_predicates_tool	Most-used predicates (with optional sample cap)
list_named_graphs_tool	Distinct named graphs
sample_of_type_tool	Sample instances of a class IRI
get_prefixes_tool	Known prefixes for the endpoint (no network call)
lindas_list_cubes_tool	cube:Cube listing
lindas_describe_cube_tool	Components of a LINDAS cube (dims / measures / attrs)
lindas_list_datasets_tool	dcat:Dataset / schema:Dataset listing
lindas_list_agents_tool	Publishing agents / organizations
parse_rdf_tool *	Parse Turtle / N-Triples / RDF-XML / JSON-LD → JSON triples
serialize_graph_tool *	JSON triples → Turtle / N-Triples / RDF-XML / JSON-LD
sparql_construct_to_graph_tool *	CONSTRUCT / DESCRIBE → rdflib-parsed graph

* available only with the rich extra installed.

Configuration

Configuration is optional. Built-in endpoints work without any config file.

Create ~/.config/sparql-mcp/endpoints.toml (or set SPARQL_MCP_CONFIG):

default_endpoint = "lindas"
max_rows = 1000

[endpoints.fuseki]
url = "http://localhost:3030/ds/sparql"
timeout = 60

[endpoints.fuseki.auth]
kind = "basic"
user = "admin"
password = "hunter2"

[endpoints.fuseki.prefixes]
ex = "http://example.org/"

[endpoints.graphdb]
url = "https://graphdb.example.org/repositories/foo"

[endpoints.graphdb.auth]
kind = "bearer"
token = "deadbeef"

[endpoints.stardog]
url = "https://sd.example.org/db/query"

[endpoints.stardog.auth]
kind = "header"
name = "X-API-Key"
value = "abc123"

Auth via environment

SPARQL_MCP_AUTH_<ALIAS> overrides the TOML auth block:

export SPARQL_MCP_AUTH_FUSEKI="Basic admin:hunter2"
export SPARQL_MCP_AUTH_GRAPHDB="Bearer deadbeef"
export SPARQL_MCP_AUTH_STARDOG="Header X-API-Key=abc123"

Safety

• Only read forms (SELECT, ASK, CONSTRUCT, DESCRIBE) are accepted.
• Update / destructive keywords (INSERT, DELETE, LOAD, CLEAR, CREATE, DROP, MOVE, COPY, ADD, WITH, USING) are blocked unconditionally in v1 — keywords appearing inside URIs or string literals are correctly ignored.
• All endpoints enforce a configurable per-query timeout (default 45s).
• list_endpoints_tool never returns auth secrets.
• TLS is verified for every outbound request.

Development

uv venv && uv pip install -e ".[dev,rich]"
.venv/bin/pytest                                 # unit tests
RUN_NETWORK_TESTS=1 .venv/bin/pytest             # + live LINDAS integration
.venv/bin/ruff check .

License

Apache-2.0 — see LICENSE.