How do I use mcp-ubergraph-query?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ubergraph-query get info for MONDO:0005015" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-ubergraph-query

by twhetzel

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Related MCP server: Redis Graph MCP Server

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

Available Tools

4 tools

get_hierarchyB

Get hierarchical relationships for a term (parents, children, ancestors, descendants).

Inputs: curie (required), relation, depth.

get_term_infoA

Get comprehensive information about a specific ontology term (labels, definitions, synonyms, types).

Inputs: curie (required), include_hierarchy.

query_ubergraphA

Execute a SPARQL query against the Ubergraph endpoint. Use for custom queries when other tools don't fit your needs.

Inputs: query (required), timeout, limit, format.

search_termsB

Search for ontology terms by label or synonym. Returns matching terms with their IDs.

Inputs: text (required), ontologies, limit, exact_match.

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-06-07 20:20 across 4 tools

Disambiguation5/5

Each tool serves a clearly distinct purpose: searching terms, retrieving term details, getting hierarchy, and executing custom SPARQL queries. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (get_hierarchy, get_term_info, query_ubergraph, search_terms), making them predictable and easy to understand.

Tool Count5/5

With 4 tools, the server is well-scoped for ontology querying. Each tool is essential and covers the primary use cases without being too few or excessive.

Completeness4/5

The tool set covers the core needs: search, term retrieval, hierarchy, and custom queries. Minimal gaps exist, such as batch operations or ontology-wide listings, but the surface is sufficient for most tasks.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

UniBio IntelligenceA
io.github.unibio-intelligence
Connect AI clients to biomedical data and tools.
Biology & Medicine Research & Data AI & Machine Learning
52
https://mcp.unibiointelligence.com/mcp
Noodle Biomedical Literature Discovery MCPA
io.github.helena-bioinformatics
Search biomedical papers, inspect publication records, and traverse citation or semantic graphs.
Bioinformatics Biology & Medicine Search
71
https://api.helena.bio/noodle/v1/mcp
copass-remote
com.olane
Knowledge graph ingestion, entity search, ontology analysis, and CoPass scoring.
Knowledge & Memory Search RAG Systems
2
https://mcp.copass.com/mcp
cosync-remote
com.olane
Knowledge graph ingestion, entity search, ontology analysis, and CoSync scoring.
Knowledge & Memory RAG Systems Search
2
https://mcp.copass.id/mcp

Related MCP Servers

OLS MCP Server
seandavi
F
license
B
quality
D
maintenance
Provides reliable access to the Ontology Lookup Service (OLS) API, enabling AI assistants to accurately search and retrieve terms from biological and medical ontologies.
Updated a year ago (2025-07-16 18:02 UTC)
7
26
-
Redis Graph MCP Server
Bioinformatics Biology & Medicine
yskale
F
license
Not graded
quality
D
maintenance
Enables LLMs and AI agents to query a biomedical knowledge graph stored in RedisGraph, with tools for concept search, synonym enrichment, and study variable discovery through semantic relationships.
Updated 6 months ago (2026-05-19 16:09 UTC)
-
mcp-ebi-ols
Open Data Bioinformatics Biology & Medicine
pipeworx-io
A
license
Not graded
quality
B
maintenance
Enables querying and browsing ontologies from the EBI Ontology Lookup Service, including searching for terms, retrieving term details, and navigating ontology hierarchies via natural language.
Updated 18 hours ago (2026-11-09 13:54 UTC)
125 npm
MIT
mcp-monarch-initiative
Biology & Medicine Bioinformatics
pipeworx-io
A
license
Not graded
quality
C
maintenance
Enables querying of the Monarch Initiative biomedical knowledge graph for genes, diseases, phenotypes, and their associations through natural language or direct tool calls.
Updated 7 days ago (2026-11-03 01:59 UTC)
466 npm
MIT

mcp-ubergraph-query

Tools

Quick Start

Prerequisites

Install

Run the server locally

Configure Claude Desktop

Configuration

Tool Reference

query_ubergraph

get_term_info

search_terms

get_hierarchy

Example SPARQL Queries

Get term label and definition

Search by label substring

Get immediate parents

Get all ancestors (transitive)

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

Testing locally

Development

Project Structure

Safety

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

OLS MCP Server

Redis Graph MCP Server

mcp-ebi-ols

mcp-monarch-initiative

`query_ubergraph`

`get_term_info`

`search_terms`

`get_hierarchy`