<div align="center">

# 🦉 OWL MCP Server

**Let AI read and write your OWL / TTL / RDF ontology files directly**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![owlready2](https://img.shields.io/badge/owlready2-latest-orange.svg)](https://pypi.org/project/owlready2/)

**English** | [简体中文](./README.zh-CN.md)

[Quick Start](#quick-start) · [Tools](#tools) · [Examples](#examples)

</div>

---

## Introduction

**OWL MCP Server** is an ontology manipulation server built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

It lets AI assistants such as Claude, Cursor, and WorkBuddy **query, modify, and reason over** your OWL/TTL/RDF ontology files as easily as ordinary files — no hand-written SPARQL, no OWL syntax details; complex knowledge-graph operations done through natural-language conversation.

```
You: "Find all individuals of class XX, sorted by amount in descending order"
AI:  [calls sparql_query] → returns structured results
```

### Use Cases

- 🏦 **Finance**: CRUD on bank-statement and invoice ontologies
- 🏥 **Healthcare**: exploration and reasoning over clinical knowledge graphs
- 🏗️ **Engineering**: management and validation of equipment and process ontologies
- 🎓 **Research**: rapid prototyping and testing of OWL ontologies

---

## Quick Start

### Step 1: Install dependencies

```bash
pip install mcp owlready2 rdflib
```

Or via requirements.txt:

```bash
pip install -r requirements.txt
```

> ⚠️ **Reasoners need Java**: `run_reasoner` (Pellet/HermiT) requires a local **JDK 8+** installation.

### Step 2: Configure your MCP client

#### WorkBuddy

Add to `~/.workbuddy/mcp.json`:

```json
{
  "mcpServers": {
    "owl": {
      "command": "python",
      "args": ["/absolute/path/server.py"]
    }
  }
}
```

> 💡 **Recommended**: use the absolute path of a virtualenv Python to avoid dependency conflicts:
> ```json
> "command": "C:/Users/yourname/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
> ```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "owl-mcp": {
      "command": "python",
      "args": ["/absolute/path/server.py"]
    }
  }
}
```

#### Cursor

Add the same configuration to `.cursor/mcp.json`, restart Cursor, and the server is available in Agent mode.

### Step 3: Enable it and start talking

In the WorkBuddy connector management page, find `owl`, click **Trust** to enable it, then just chat in natural language:

```
"Load the ontology file C:/work/xxxx.ttl"
"List all classes, only the ones starting with xxx:"
"Describe the full structure of the BankStatement class"
"Run the HermiT reasoner to check ontology consistency"
"Save the new classes back to the original file"
```

---

## Tools

### 📖 Query tools

| Tool | Description |
|------|-------------|
| `load_ontology` | Load an ontology file (local path or IRI; formats: TTL / OWL / RDF) |
| `get_ontology_info` | Get an overview (counts of classes, individuals, properties; namespaces) |
| `list_classes` | List all classes, with prefix filtering and limit |
| `list_individuals` | List all individuals, optionally filtered by class |
| `list_properties` | List object properties / data properties |
| `describe_class` | Describe a class in detail (parents, children, restrictions, known individuals) |
| `describe_individual` | Describe an individual (types and all property values) |
| `search_entity` | Fuzzy-search classes / individuals / properties by keyword |
| `sparql_query` | Run a SPARQL 1.1 SELECT query |

### ✏️ Modification tools

| Tool | Description |
|------|-------------|
| `add_class` | Add a new class (with optional parent, rdfs:label, rdfs:comment) |
| `add_individual` | Add a new individual (with optional initial property values) |
| `add_object_property_assertion` | Add an object-property triple assertion |
| `save_ontology` | Save the ontology (rdfxml / turtle / ntriples) |

### 🧠 Reasoning tools

| Tool | Description |
|------|-------------|
| `run_reasoner` | Run a reasoner (Pellet or HermiT) to check consistency and infer implicit knowledge |

> **Note**: `add_*` operations are not saved automatically — call `save_ontology` explicitly.

---

## Examples

### Exploring the ontology structure

```
You: Load xxx.ttl and give me an overview
AI:  This ontology has 47 classes, 213 individuals, 18 object properties...

You: Describe the BankStatement class
AI:  BankStatement is a subclass of FinancialDocument, with the following data
     properties: amount, currency, date...
```

### SPARQL queries

```sparql
-- Find all BankStatement individuals and their amounts (descending)
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX : <http://test.com/t#>

SELECT ?ind ?amount WHERE {
  ?ind rdf:type :BankStatement .
  ?ind :amount ?amount .
}
ORDER BY DESC(?amount)
```

### Incremental modification

```
You: Add a new class AA whose parent is BB, with label "CC"
AI:  [calls add_class] → class AA added

You: Save the change in turtle format
AI:  [calls save_ontology] → saved to xxx.ttl
```

### Consistency checking

```
You: Run the HermiT reasoner and check the ontology for logical contradictions
AI:  [calls run_reasoner] → the ontology is consistent; 3 new implicit class
     memberships were inferred...
```

---

## Tech Stack

| Component | Purpose |
|-----------|---------|
| [owlready2](https://pypi.org/project/owlready2/) | OWL ontology loading, modification, reasoner invocation |
| [rdflib](https://rdflib.readthedocs.io/) | SPARQL 1.1 query engine |
| [mcp](https://github.com/modelcontextprotocol/python-sdk) | Model Context Protocol SDK |

---

## Notes

- **Reasoners need Java**: Pellet / HermiT depend on JDK 8+; make sure `java` is on your system PATH
- **Large ontologies**: beyond ~100k triples, use the `limit` parameter with the `list_*` tools
- **Changes are not auto-saved**: all `add_*` operations only update the in-memory model; call `save_ontology` explicitly
- **SPARQL syntax**: standard SPARQL 1.1, executed by the rdflib engine

---

## Compatible MCP Clients

- ✅ WorkBuddy
- ✅ Trae/Traw-work
- ✅ Claude
- ✅ Cursor (Agent mode)
- ✅ Any MCP-compliant AI client

---

## License

[MIT](LICENSE)

---

## ☕ Buy Me a Coffee

OWL MCP Server is an open-source project I develop and maintain in my spare time, and it will stay free forever.

If it has saved you even half an hour of hand-writing SPARQL, consider buying me a coffee (¥9.9 is enough ☕) — every bit of support goes straight into new features and bug fixes.

<p align="center">
  <img src="icon.jpg" alt="Donation QR code - buy the author a coffee" width="280">
</p>

<p align="center"><i>When donating, feel free to mention the feature you want most — I'll prioritize it 😉</i></p>

**Prefer not to donate?** Giving the project a ⭐ Star, opening an Issue, or sharing it with someone who needs it is equally great support!

---