mcp-ubergraph-query

An MCP server for querying the Ubergraph biomedical ontology SPARQL endpoint.

Ubergraph is a merged knowledge graph of OBO ontologies including MONDO, UBERON, HP, CHEBI, GO, CL, and more. This server exposes four tools that let AI assistants query it naturally.

Tools

Tool	Description
query_ubergraph	Execute custom SPARQL SELECT queries
get_term_info	Get label, definition, synonyms, and types for an ontology term
search_terms	Search terms by label or synonym across ontologies
get_hierarchy	Traverse parents, children, ancestors, or descendants

Quick Start

Prerequisites

• Python 3.10+
• uv

Install

git clone https://github.com/twhetzel/mcp-ubergraph-query
cd mcp-ubergraph-query
uv sync --all-extras

Run the server locally

The server uses stdio (stdin/stdout) for MCP transport. Start it with:

uv run mcp-ubergraph-query

Or:

uv run python -m ubergraph_query.server

Leave this process running; MCP clients (e.g. Claude Desktop, Cursor) connect by spawning this command and talking over stdin/stdout.

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ubergraph": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-ubergraph-query",
        "run",
        "mcp-ubergraph-query"
      ]
    }
  }
}

Configuration

Copy .env.example to .env and adjust as needed:

cp .env.example .env

Variable	Default	Description
UBERGRAPH_ENDPOINT	https://ubergraph.apps.renci.org/sparql	SPARQL endpoint URL
QUERY_TIMEOUT_DEFAULT	30	Default query timeout (seconds)
QUERY_LIMIT_MAX	1000	Maximum allowed LIMIT value
ENABLE_QUERY_CACHE	true	Enable in-memory LRU result cache
CACHE_TTL_SECONDS	3600	Cache entry lifetime
LOG_LEVEL	INFO	Logging verbosity

Tool Reference

query_ubergraph

Execute a custom SPARQL SELECT query against Ubergraph.

Input:

{
  "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5",
  "timeout": 30,
  "limit": 100,
  "format": "json"
}

Output:

{
  "results": [{"s": "...", "p": "...", "o": "..."}],
  "query_time_ms": 234,
  "result_count": 5,
  "query_hash": "abc123def456"
}

Safety features: LIMIT is automatically injected if absent; write operations (INSERT, DELETE, DROP, etc.) are rejected; timeout is capped at 60 s.

---

get_term_info

Get comprehensive metadata for an ontology term by CURIE.

Input:

{
  "curie": "MONDO:0005015",
  "include_hierarchy": false
}

Output:

{
  "curie": "MONDO:0005015",
  "iri": "http://purl.obolibrary.org/obo/MONDO_0005015",
  "label": "diabetes mellitus",
  "definition": "A metabolic disorder characterized by...",
  "synonyms": ["DM", "diabetes"],
  "types": ["owl:Class"],
  "in_ontology": "mondo"
}

With include_hierarchy: true, parents and children arrays are added.

---

search_terms

Search ontology terms by label or synonym.

Input:

{
  "text": "diabetes",
  "ontologies": ["MONDO", "HP"],
  "limit": 10,
  "exact_match": false
}

Output:

{
  "matches": [
    {
      "curie": "MONDO:0005015",
      "label": "diabetes mellitus",
      "match_type": "partial",
      "ontology": "mondo",
      "score": 0.6
    }
  ],
  "search_text": "diabetes",
  "total_matches": 1
}

---

get_hierarchy

Traverse hierarchical relationships for a term.

Input:

{
  "curie": "MONDO:0005015",
  "relation": "parents",
  "depth": 1
}

relation values: parents, children, ancestors, descendants

Output:

{
  "curie": "MONDO:0005015",
  "relation": "parents",
  "depth": 1,
  "terms": [
    {"curie": "MONDO:0005066", "label": "metabolic disease", "distance": 1}
  ]
}

Example SPARQL Queries

Get term label and definition

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX obo:  <http://purl.obolibrary.org/obo/>
SELECT ?label ?definition WHERE {
  obo:MONDO_0005015 rdfs:label ?label .
  OPTIONAL { obo:MONDO_0005015 obo:IAO_0000115 ?definition }
}

Search by label substring

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?term ?label WHERE {
  ?term rdfs:label ?label .
  FILTER(CONTAINS(LCASE(?label), "diabetes"))
  FILTER(STRSTARTS(STR(?term), "http://purl.obolibrary.org/obo/MONDO_"))
}
LIMIT 10

Get immediate parents

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX obo:  <http://purl.obolibrary.org/obo/>
SELECT ?parent ?label WHERE {
  obo:MONDO_0005015 rdfs:subClassOf ?parent .
  FILTER(!isBlank(?parent))
  OPTIONAL { ?parent rdfs:label ?label }
}

Get all ancestors (transitive)

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX obo:  <http://purl.obolibrary.org/obo/>
SELECT ?ancestor ?label WHERE {
  obo:MONDO_0005015 rdfs:subClassOf+ ?ancestor .
  FILTER(!isBlank(?ancestor))
  OPTIONAL { ?ancestor rdfs:label ?label }
}
LIMIT 100

Find phenotype terms for a disease (HP + MONDO cross-ontology)

PREFIX rdfs:    <http://www.w3.org/2000/01/rdf-schema#>
PREFIX obo:     <http://purl.obolibrary.org/obo/>
PREFIX oboInOwl: <http://www.geneontology.org/formats/oboInOwl#>
SELECT ?phenotype ?label WHERE {
  ?association obo:RO_0002200 obo:MONDO_0005015 ;
               obo:RO_0002200 ?phenotype .
  FILTER(STRSTARTS(STR(?phenotype), "http://purl.obolibrary.org/obo/HP_"))
  OPTIONAL { ?phenotype rdfs:label ?label }
}
LIMIT 20

Testing locally

The project is not on PyPI yet. Install and test from the repo:

# Install with dev dependencies (includes pytest)
uv sync --all-extras

# Run unit tests (no network)
uv run python -m pytest tests/ -v

# Test the MCP server: spawns server, lists tools, calls get_term_info, search_terms, get_hierarchy
uv run python examples/test_mcp_server.py

# Run direct SPARQL/query examples (hits Ubergraph)
uv run python examples/example_usage.py

Manual testing with MCP Inspector:
Run the server with uv run mcp-ubergraph-query, then use MCP Inspector and add a stdio server with command uv, args --directory, <path-to-this-repo>, run, mcp-ubergraph-query.

Development

# Lint
uv run ruff check src/ tests/

Project Structure

mcp-ubergraph-query/
├── src/
│   └── ubergraph_query/
│       ├── __init__.py        # Package metadata
│       ├── server.py          # MCP server + tool implementations
│       ├── sparql_client.py   # Async HTTP SPARQL execution with retries
│       ├── query_builder.py   # SPARQL query construction helpers
│       ├── cache.py           # Thread-safe LRU cache with TTL
│       ├── validators.py      # CURIE validation, query safety checks
│       └── config.py          # Environment-based configuration
├── tests/
│   └── test_queries.py        # Unit tests (no network required)
├── examples/
│   └── example_usage.py       # Live query examples
├── pyproject.toml
├── .env.example
└── README.md

Safety

• Read-only: Write operations (INSERT, DELETE, DROP, etc.) are rejected
• LIMIT enforcement: Queries without LIMIT get one injected; over-limit values are capped
• Timeout cap: Hard maximum of 60 seconds per query
• Retry with backoff: Transient 5xx/network errors are retried up to 3 times
• Query logging: Every query is logged with a SHA-256 hash for provenance

License

MIT