MCP Ontology Annotator

An MCP (Model Context Protocol) server for mapping biomedical text to standardized ontology terms.

Features

• annotate_ontology_terms — Map specific terms to ontology IDs via a multi-stage pipeline:
  1. Exact label match (OLS)
  2. Synonym match (OLS)
  3. Fuzzy search (OLS)
  4. BioPortal fallback (optional, requires API key)
• extract_and_annotate — Extract biomedical entities from free text using Claude, then annotate each entity.
• Supports domains: disease, chemical, gene, phenotype, anatomy, organism
• Configurable default ontologies per domain
• Retry with exponential back-off on API failures

Requirements

• Python 3.10+
• uv for dependency management

Setup

# Clone the repo
git clone <repo-url>
cd mcp-ontology-annotator

# Create and activate virtual environment with uv
uv venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Install the package and dependencies
uv pip install -e ".[dev]"    # includes dev/test dependencies
# or just the runtime:
uv pip install -e .

Environment Variables

Copy .env.example to .env and fill in values:

cp .env.example .env

Running the MCP Server

# After installing with uv pip install -e .
ontology-annotator
# or
python -m ontology_annotator.server

The server communicates over stdio, as required by the MCP protocol.

Claude Desktop Configuration

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

{
  "mcpServers": {
    "ontology-annotator": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/ontology-annotator-mcp",
        "ontology-annotator"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "BIOPORTAL_API_KEY": ""
      }
    }
  }
}

Running Tests

pytest

Linting

ruff check src tests
ruff format src tests

Example Usage

python examples/example_usage.py

Tool Reference

annotate_ontology_terms

extract_and_annotate

Project Structure

ontology-annotator-mcp/
├── src/
│   └── ontology_annotator/
│       ├── __init__.py
│       ├── server.py           # MCP server
│       ├── annotator.py        # Multi-stage annotation pipeline
│       ├── extractor.py        # LLM entity extraction
│       ├── ols_client.py       # OLS4 API client
│       ├── bioportal_client.py # BioPortal API client (optional)
│       └── config.py           # Settings via env vars
├── tests/
│   └── test_annotator.py
├── examples/
│   └── example_usage.py
├── pyproject.toml
├── .env.example
└── README.md