# 🦉 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)

--- ## 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: PREFIX : 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.

When donating, feel free to mention the feature you want most — I'll prioritize it 😉

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