OWL MCP

A high-performance Model Context Protocol (MCP) server and CLI for OWL ontology management, written in Rust.

Built as a drop-in replacement for ai4curation/owl-mcp, designed to eliminate the crashes and timeouts inherent to the Python implementation. Axioms are expressed in OWL Functional Syntax.

Features

• 18 MCP tools — add, remove, search, and inspect axioms; add structured assertions (data/annotation/object property, class) with the literal value as a separate field; manage prefixes, labels, and ontology IRIs; scan for modeling pitfalls; evaluate ontology quality; check logical consistency with an OWL 2 EL reasoner; run SPARQL queries; verbalize OWL into Controlled Natural Language
• CLI mode — every tool is also available as a direct CLI subcommand (owl-mcp find-axioms ...)
• 2 transport modes — stdio (default, for Cursor/Claude Desktop) and http (Streamable HTTP, MCP 2026-07-28, sessionless)
• Disk as source of truth — each tool call takes owl_file_path; the in-memory cache reloads when the file's mtime changes. resource://active lists files currently cached in this process (not durable state)
• Live file watching — a 5s watcher is a local optimization; mtime-on-access is what keeps the cache correct
• OFN and RDF/XML support — reads and writes both formats; format is auto-detected from file extension and content
• Never crashes — errors are returned as MCP tool failures, not panics

Installation

via npx (recommended)

npx owl-mcp serve

via npm (global install)

npm install -g owl-mcp
owl-mcp --help

Build from source

Requires Rust 1.88+.

git clone https://github.com/Minitour/owl-mcp
cd owl-mcp
cargo build --release
./target/release/owl-mcp --help

Usage

owl-mcp has two modes: serve (MCP server) and CLI (direct commands).

MCP server mode

owl-mcp serve [OPTIONS]

Options:
  --transport <stdio|http>   Transport to use [default: stdio]
  --host <HOST>              Host to bind (HTTP only) [default: 127.0.0.1]
  --port <PORT>              Port to bind (HTTP only) [default: 8080]

CLI mode

Every MCP tool is available as a subcommand:

owl-mcp add-axiom --file ontology.owl --axiom "SubClassOf(:Dog :Animal)"
owl-mcp add-data-property-assertion --file ontology.owl --property :metaprops --subject :Plan1 --value-file ./long-value.txt
owl-mcp add-axioms --file ontology.owl --axioms-file ./axioms.json
owl-mcp find-axioms --file ontology.owl --pattern "Dog" --limit 50
owl-mcp get-all-axioms --file ontology.owl --include-labels
owl-mcp test-pitfalls --file ontology.owl
owl-mcp test-quality --file ontology.owl
owl-mcp sparql --file ontology.owl --query "SELECT ?c WHERE { ?c a owl:Class }"
owl-mcp sparql --file schema.owl --file data.owl --query "ASK { ?i a :Plan }"
owl-mcp reason --file ontology.owl
owl-mcp reason --file schema.owl --file data.owl --output reasoned.ofn
owl-mcp verbalize --file ontology.owl
owl-mcp verbalize --file ontology.owl --iri http://example.org/pizza#Margherita --limit 10

Run owl-mcp --help for a full list of commands, or owl-mcp <command> --help for details on a specific command.

Cursor / Claude Desktop integration

Add the server to your MCP client configuration.

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "owl-mcp": {
      "command": "npx",
      "args": ["-y", "owl-mcp", "serve"]
    }
  }
}

HTTP transport (useful for remote/shared setups):

{
  "mcpServers": {
    "owl-mcp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Start the server with:

owl-mcp serve --transport http --port 8080

Tools

All tools operate on OWL files by absolute path. The manager lazily loads files on first access and caches them in this process. Each access reloads from disk if the file's modification time has changed, so the cache is not protocol or session state.

Axiom operations

| Tool | Description | |---|---| | add_axiom | Add a single axiom in OWL Functional Syntax | | add_axioms | Add multiple axioms in one call | | add_data_property_assertion | Assert a data property value (value passed as a separate field — no escaping) | | add_annotation_assertion | Assert an annotation value (value passed as a separate field — no escaping) | | add_object_property_assertion | Link two individuals via an object property | | add_class_assertion | Assert that an individual is an instance of a class | | remove_axiom | Remove an axiom | | find_axioms | Search axioms with a regex pattern | | get_all_axioms | List all axioms (up to a limit) |

For long or special-character literal values (containing ;, =, /, ,, quotes, or newlines), prefer the structured assertion tools over hand-writing a quoted add_axiom string: they take the value as a separate field and build the axiom server-side, so no escaping is needed. In CLI mode, add-axioms also accepts --axioms-file <path> (a JSON array of strings, or NUL/newline-delimited; - for stdin), and the structured commands accept --value-file <path>, both of which bypass shell quoting entirely. add_axiom/add_axioms now return a hard error (instead of a silent warning) when an input parses to no axiom.

Metadata and labels

| Tool | Description | |---|---| | add_prefix | Add a prefix mapping (ex: → http://example.org/) | | ontology_metadata | Return ontology-level annotation axioms | | get_labels_for_iri | Look up rdfs:label (or custom property) values for an IRI | | set_ontology_iri | Set or update the ontology IRI and version IRI |

Quality checks

| Tool | Description | |---|---| | test_pitfalls | Scan for 31 common modeling pitfalls (inspired by OOPS!) | | test_quality | Evaluate ontology quality using the OQuaRE framework (ISO/IEC 25000 SQuaRE) |

find_axioms and get_all_axioms accept include_labels: true to annotate each axiom with human-readable labels appended as ## <IRI> # label comments.

test_quality uses the whelk OWL EL reasoner to compute inferred class hierarchy and returns a JSON report containing 19 raw and scaled metrics (ANOnto, AROnto, CBOOnto, CROnto, DITOnto, INROnto, LCOMOnto, NACOnto, NOCOnto, NOMOnto, RFCOnto, RROnto, TMOnto, WMCOnto, and variants), 22 subcharacteristics, 7 quality characteristics (Structural, Functional Adequacy, Maintainability, Operability, Reliability, Transferability, Compatibility), and an overall OQuaRE score on a 1–5 scale.

Querying and reasoning

| Tool | Description | |---|---| | sparql_query | Run a SPARQL query over one or more OWL files | | check_consistency | Run an OWL 2 EL reasoner and report consistency / unsatisfiable classes |

sparql_query takes owl_file_paths (one or more absolute paths) and a query string. Each file is serialized to RDF and loaded together into an in-memory oxigraph store, so passing several paths merges a schema with its ABox or imports before the query runs. SELECT and ASK return the standard SPARQL 1.1 JSON results format; CONSTRUCT and DESCRIBE return a list of N-Triples. By default queries run over asserted triples only. Set with_reasoning: true to materialize OWL 2 EL entailments (via whelk) before querying so inferred subclass relationships are visible.

check_consistency (CLI: owl-mcp reason) takes owl_file_paths (merged like sparql_query), an optional reasoner (whelk default; elk is accepted as a synonym), and an optional output_path to write a materialized ontology (asserted + inferred SubClassOf axioms). It returns JSON with consistent, unsatisfiable_classes, optional inferred_axioms_count, and reasoner. Profile limitation: whelk/ELK reason within OWL 2 EL only — full OWL 2 DL inconsistency (cardinality restrictions, complex disjointness outside EL, etc.) is not detected. This is a faithful replacement for robot reason --reasoner ELK, not a DL-complete reasoner.

Verbalization

| Tool | Description | |---|---| | verbalize | Convert OWL axioms into Controlled Natural Language (pseudo-text) plus a Turtle fragment |

verbalize (CLI: owl-mcp verbalize --file ontology.owl [--iri ...] [--limit N]) takes owl_file_path, an optional iri (CURIE or full IRI), and an optional limit (default 100). If iri is omitted, it verbalizes owl:Class and owl:NamedIndividual entities, skipping owl:deprecated. The result is a JSON array of {root, fragment, text, statements, unique_concepts, unique_relationships}. CNL uses the same default ignore/rephrase maps as ontology-verbalizer (rdfs:subClassOf → "is a type of", owl:disjointWith → "is different from", owl:unionOf → "any of", etc.). There is no LLM paraphrasing.

The MCP HTTP transport is Streamable HTTP at /mcp (protocol 2026-07-28, no Mcp-Session-Id). stdio remains compatible with the 2025-11-25 handshake used by Cursor and Claude Desktop.

Development

# Run tests
cargo test

# Check formatting and lints
cargo fmt --check
cargo clippy --all-targets -- -D warnings

# Build release binary
cargo build --release

License

MIT