Skip to main content
Glama

sparql-mcp

MCP servers that let an LLM host (Claude Code, Claude Desktop, an IDE) answer questions from public SPARQL endpoints without guessing their vocabulary. One engine, one profile per endpoint:

profile

endpoint

release reported from

wikipathways

https://sparql.wikipathways.org/sparql

VoID graph (https://data.wikipathways.org/<date>/rdf/)

aopwiki

https://aopwiki.rdf.bigcat-bioinformatics.org/sparql

VoID graph (pav:version, weekly build)

Why

The obvious query is often wrong in a way that looks right. In WikiPathways, SELECT (COUNT(?pw) AS ?n) WHERE { ?pw a wp:Pathway } returns about 3,000, but only about 2,200 of those are pathways. The rest are boxes that refer to a pathway from inside another one. In AOP-Wiki, the most common classes are identifier types, not AOPs, and half of the taxonomic-applicability values are strings rather than NCBITaxon IRIs. These servers give the model what it needs to avoid such mistakes before it writes the query:

  • get_schema_card: named graphs, classes with instance counts, every predicate used on the main classes with usage counts and an example value, the known pitfalls of the dataset, and the prefixes. It is built from the live endpoint, cached for an hour, and replaced by a committed snapshot only when the live build fails.

  • resolve_entity: real IRIs from a name or ID (pathways, genes and metabolites; AOPs, key events, KERs, stressors and genes), so the model never builds an IRI by hand.

  • search_examples / get_example: the curated example queries the endpoint itself publishes (SHACL sh:select examples in its .well-known/sparql-examples graph).

  • run_sparql: read-only execution with guardrails and repair advice (below).

Every tool response carries a source block with the dataset, endpoint, release version and date and licence. Over HTTP, responses also carry an X-Dataset-Version header.

Related MCP server: BioBTree

Guardrails

The guard is a defence in depth. Both endpoints are public and the WikiPathways one is read-only anyway. The guard still checks every query before it reaches the endpoint:

  • rejects writes (INSERT, DELETE, LOAD, CLEAR, DROP, ...), also when hidden behind an IRI containing # on the same line;

  • rejects Virtuoso extensions: DEFINE pragmas and bif: / sql: functions, including when written as IRIs or bound to another prefix;

  • rejects SERVICE, so the server cannot be used as a proxy to other endpoints;

  • rejects unanchored full scans (only variables in every pattern, plus an aggregate, DISTINCT or sorting) and points to the schema card, which already has those counts;

  • appends LIMIT 100 when no limit is given and caps results at 1,000 rows;

  • adds PREFIX lines for the profile's known prefixes when the query uses them without declaring them.

Errors, timeouts, partial results and empty results come back with advice the model can act on. At most four queries per replica run against an endpoint at the same time.

Use

Hosted instances (streamable HTTP, no authentication):

claude mcp add -s user --transport http wikipathways https://wikipathways-mcp.cloud.vhp4safety.nl/mcp
claude mcp add -s user --transport http aopwiki https://aopwiki-mcp.cloud.vhp4safety.nl/mcp

Locally over stdio (Python 3.12 and uv):

uv sync
claude mcp add -s user wikipathways -- uv --directory /path/to/sparql-mcp run sparql-mcp --profile wikipathways

Or with Docker:

docker run --rm -p 8080:8080 -e PROFILE=aopwiki ghcr.io/marvinm2/sparql-mcp:main
# MCP endpoint: http://localhost:8080/mcp, health: http://localhost:8080/health

Configuration

variable

default

purpose

PROFILE

(required)

wikipathways or aopwiki

MCP_TRANSPORT

stdio (http in the image)

stdio or http

MCP_HOST, MCP_PORT

127.0.0.1, 8080

HTTP bind address

MCP_ALLOWED_HOSTS

(empty)

comma-separated Host values to accept (DNS-rebinding protection); empty accepts any host when bound to a public interface

MCP_ALLOWED_ORIGINS

(empty)

comma-separated browser origins to accept, used with MCP_ALLOWED_HOSTS

MCP_SERVER_NAME

<profile>-sparql

server name reported in initialize

SPARQL_ENDPOINT

profile's endpoint

point a profile at a mirror

Adding a profile

A profile is src/sparql_mcp/profiles/<name>.py (a PROFILE object: endpoint, named graphs and the classes to describe, prefixes, a release query, resolvers) plus <name>_traps.md (the pitfalls, in prose). Register it in profiles/__init__.py, check every claim in the traps file against the live endpoint, and write the fallback card with sparql-mcp --profile <name> --write-snapshot.

Development

uv sync
uv run pytest           # guard, resolvers (including injection attempts), execution helpers
uv run ruff check src tests

Credits

The schema-card design (live card, entity resolution, guarded execution with repair advice) follows the OntoPortal-MCP-Over-SPARQL server for AgroPortal. This is an independent implementation.

Licence

Code: MIT. The data served by the endpoints keeps its own licence: WikiPathways CC0 1.0, AOP-Wiki CC BY-SA 4.0. Each tool response states it.

Available Tools

5 tools
get_exampleGet one curated example queryA
Read-only

Return the full SPARQL text and description of one curated example, by the id that search_examples gave.

Inputs: id (required). Returns: result

get_schema_cardGet the AOP-Wiki RDF schemaA
Read-only

Return the AOP-Wiki RDF schema card: the named graphs and what each holds, the classes with instance counts, every predicate used on the main classes with usage counts and an example value, the known pitfalls of this dataset, and the prefixes. Call this once before writing your first SPARQL query in a conversation. Built from the live endpoint, so its counts are current.

Inputs: no named parameters. Returns: result

resolve_entityResolve a AOP-Wiki RDF entityA
Read-only

Look up the real IRIs of AOP-Wiki RDF entities from a name or identifier. Call this before writing any query that mentions a specific entity; never build these IRIs by hand. Kinds:

  • aop: an AOP by number ('AOP 1', '1') or title fragment ('liver fibrosis')

  • key_event: a key event by number ('KE 142') or title fragment ('hyperplasia'); also MIEs and AOs

  • ker: a key event relationship by number ('KER 158') or by a fragment of its upstream or downstream KE title

  • stressor: a stressor by number ('Stressor 50'), CAS number ('83-79-4') or name fragment ('rotenone')

  • gene: an HGNC gene by symbol ('TP53') or HGNC number; returns how many KEs are linked to it species (optional, Latin name such as 'Homo sapiens') narrows kinds that have a species.

Inputs: kind (required), term (required), species. Returns: result

run_sparqlRun SPARQL against AOP-Wiki RDFA
Read-only

Run a read-only SPARQL 1.1 query against https://aopwiki.rdf.bigcat-bioinformatics.org/sparql and return the rows as JSON. Writes, Virtuoso extensions (DEFINE, bif:, sql:), SERVICE and unanchored full scans are rejected; a missing LIMIT becomes LIMIT 100 and the ceiling is 1000 rows. Known prefixes are added when you forget them. Errors, timeouts and empty results come back with advice on how to repair the query: read it and try again rather than giving up.

Orientation: All content is in GRAPH http://aopwiki.org/. Entities are identifiers.org IRIs: AOPs https://identifiers.org/aop/N, KEs https://identifiers.org/aop.events/N, KERs https://identifiers.org/aop.relationships/N, stressors https://identifiers.org/aop.stressor/N. AOP structure: aopo:has_molecular_initiating_event, aopo:has_key_event, aopo:has_adverse_outcome, aopo:has_key_event_relationship; KERs use aopo:has_upstream_key_event / aopo:has_downstream_key_event. Several metadata predicates are opaque ontology IRIs (ncit:C25664 = level of biological organisation, ncit:C54571 = stressor, ncbitaxon:131567 = taxonomic applicability); the schema card lists them all.

Inputs: query (required). Returns: result

search_examplesSearch AOP-Wiki RDF's curated example queriesA
Read-only

Search the curated example SPARQL queries that AOP-Wiki RDF publishes on its endpoint, by words describing what you want (e.g. 'pathways for a gene', 'count by species'). Returns ids and descriptions; fetch the full query with get_example. Adapting a curated example is faster and more reliable than writing a query from scratch.

Inputs: text (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool occupies a distinct slot in a clear workflow: schema orientation (get_schema_card), entity IRI resolution (resolve_entity), execution (run_sparql), and example discovery/retrieval (search_examples vs get_example). The search/fetch pair is a well-understood pattern with non-overlapping roles. No tool can plausibly be mistaken for another.

    Naming Consistency5/5

    All five names follow the same lower_snake_case verb_noun pattern: get_schema_card, resolve_entity, run_sparql, search_examples, get_example. The verbs are accurate and consistent (get_ for retrieval, search_ for discovery, run_ for execution). No style mixing.

    Tool Count5/5

    Five tightly scoped tools for a read-only SPARQL endpoint is right-sized; each one maps to a real step an agent must take (orient, resolve IRIs, query, find examples). Nothing feels padded or absent for the stated scope.

    Completeness4/5

    The surface covers the full query lifecycle: schema discovery, entity resolution, example search/fetch, and execution with self-repairing error feedback. Minor gaps remain — no result pagination/continuation beyond the 1000-row ceiling and no standalone prefix or graph-listing helper (both only indirectly available via the schema card) — but agents can work around these with SPARQL itself.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to write and execute SPARQL queries against open-access SPARQL endpoints by providing relevant query examples, schema information, and endpoint metadata. Supports querying biological databases like UniProt and Bgee through natural language interactions.
      12
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A unified biomedical graph database that integrates 50+ primary data sources — genes, proteins, compounds, diseases, pathways, and clinical data — into a single queryable graph with billions of cross-reference edges. Its native MCP server gives LLMs direct access to structured, authoritative biomedical data, complementing their reasoning with reliable identifiers and up-to-date database content.
      20
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server exposing SPARQL query functionalities for LLMs, enabling query execution, validation, and graph exploration across SPARQL endpoints.
      7
      79 PyPI
      MIT