SPARQL MCP
# sparql-mcp
[MCP](https://modelcontextprotocol.io) 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.
## 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):
```bash
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](https://docs.astral.sh/uv/)):
```bash
uv sync
claude mcp add -s user wikipathways -- uv --directory /path/to/sparql-mcp run sparql-mcp --profile wikipathways
```
Or with Docker:
```bash
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
```bash
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.
TDQS
Scored across 5 tools
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.
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.
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.
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.