# auto-ontology-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/gogoymh/auto-ontology-mcp  
**GitHub Stars:** 273  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/auto-ontology-mcp

## Description
NVIDIA Auto Ontology's semantic layer and a personal knowledge base as an MCP server for Claude, ChatGPT and other MCP clients. No LLM API key needed.

## Tools
Capabilities this server exposes over MCP:

- **check_readiness** — Report every datasource's state: whether SQL can run against it, how much is modeled (Terms,
relationships, SQL attributes), knowledge store counts, and the next step. Call it first in
a session and whenever a question fails unexpectedly. Read-only.
- **add_datasource** — Register a database by SQLAlchemy URL, test the connection and, by default, scan it. Use it only
when the user gives you a URL; never invent credentials. Connections are opened
read-only and nothing is ever written to the database. Re-using a name replaces that
datasource's URL. Fails with the driver or connection error if the database cannot
be reached; use scan_datasource to re-read one that is already registered.
- **scan_datasource** — Re-read a registered database: tables, columns, declared keys, column profiles (samples,
uniqueness, formats, small value sets) and undeclared keys inferred by name and
confirmed by value containment. Use it after the schema changed or to refresh
profiles; add_datasource already scans once. Terms, reviewed relationships and SQL
attributes are kept; inferred relationships that lost their evidence are removed.
Reports new tables and columns added to modeled tables; get_modeling_worklist returns
both. Reads the database only.
- **get_modeling_worklist** — Return the next tables that still have no business Terms, with what you need to name them: candidate
columns (types, samples, uniqueness, formats), foreign keys and the Terms they point to, and
the modeling rules. Use it while building an ontology over a database; call save_table_terms
once per returned table and repeat until remaining is 0. After a re-scan it also returns
modeled tables that gained columns, with new_columns and current_terms: send current_terms
back with each new column added to its Term. For the personal knowledge store use
define_entity instead. Read-only.
- **save_table_terms** — Save the Terms you propose for one database table and map its columns to them. Use it for tables
returned by get_modeling_worklist; use update_term to edit a single Term afterwards. It
replaces the table's previous Terms: same-named Terms are updated, others are removed unless
they own SQL attributes. Unassigned candidate columns go to the first Term. Nothing is saved
if a column is unknown, assigned twice, or a name clashes with another table's Term; the
error lists every problem. New Terms are drafts.
- **list_relationships** — List joins between tables with their evidence (declared, inferred with name score and value
containment, or added manually), plus multi-role joins, identifier columns with no
relationship, and joins used by executed queries that are not relationships yet. Use it to
review the join graph before modeling or when a join looks wrong; act on it with
set_relationship. Use find_join_path for the route between two Terms. Read-only.
- **set_relationship** — Change one join between two columns: accept or reject a proposed one, add a missing one, update its
role, description or default flag, or delete it. Use it after list_relationships. Identify
it by relationship_id or by source and target ('table.column'). Reviewed relationships
survive re-scans; only accepted ones are used for join paths. delete removes it permanently;
rejecting keeps the decision instead. Fails if the columns or relationship do not exist.
- **suggest_sql_attributes** — Return candidate SQL attributes (reusable measures, filters and join patterns) mined from queries
run through this server, verified examples, bridge tables and column profiles, with the
rules for judging them. Use it after Terms exist; save the worthwhile ones with
save_sql_attribute and ignore the rest. Read-only.
- **save_sql_attribute** — Create, update, certify or delete a named SQL expression under a Term. Before saving, the expression
is run read-only against the database (a fragment over the Term's table, or a full SELECT
for join/query kinds); if the database rejects it, nothing is saved and the error is
returned. Changing a certified attribute's expression returns it to draft. delete=true
removes it permanently. Use suggest_sql_attributes to find candidates.
- **update_term** — Edit one existing Term: rename it, change its description or synonyms, rename or describe its mapped
columns, set its status, or delete it. Use add_synonyms to record the user's own words so
searches match them. Changing a certified Term's name or description returns it to draft
unless you also pass status; only certify what the user confirmed. delete=true removes the
Term with its column mappings, SQL attributes and relations and cannot be undone; knowledge
entities must be deleted with define_entity. For concept bodies and relations use
save_concept.
- **save_glossary** — Add, update or delete glossary entries for abbreviations and jargon (MRR → monthly recurring
revenue), per datasource or global. Entries are searched like Terms and returned by
get_query_context. Use it for words to expand, not for business definitions with columns,
which are Terms. Deleted entries are gone.
- **define_entity** — Create an entity in the personal knowledge store (a Term with its own table of records), add columns to it as you learn more, or delete it. Search first (search_ontology or list_terms) and reuse an existing entity. Use entities for facts you will count, sum, filter or compare; use save_concept for definitions and explanations. Column types: text, integer, number, date, datetime, boolean, ref:<Entity> (a link that becomes a relationship). Names are snake_case English (pass table= when the entity name is not English); keys make re-adding a record update it. Existing column types cannot change. delete=true drops the entity; with force=true its records are deleted too, which cannot be undone. Then store rows with add_records.
- **add_records** — Store records in a knowledge entity (from receipts, statements, notes, logs the user shared), each
with its source, locator and supporting quote. The whole batch is validated first: values
are normalized ('12,000원' → 12000, '2026/10/03' → 2026-10-03), references resolved by id or
name (missing ones created), and if any record is invalid nothing is written and every
problem is listed. Records matching an existing one by key, or identical ones, update or are
skipped instead of duplicating. Use edit_records to change records by id.
- **edit_records** — Update or delete knowledge records by id (find ids with run_sql or get_source). update sets the
given columns and provenance fields. delete is permanent and is refused while other records
reference the rows; confirm with the user first. Use add_records to insert new records and
define_entity to change columns.
- **save_concept** — Create or update a concept: a Term with a one-line definition, a markdown body (a wiki page) and
typed relations (is_a, part_of, related_to, ...) to other Terms, with its source. Use it for
ideas and explanations; use define_entity and add_records for countable facts. Also works on
existing entity Terms to explain them. body replaces the page and append_body adds to it;
relation targets that do not exist yet are created as empty concepts. Changing a certified
concept's meaning returns it to draft.
- **save_passages** — Save excerpts and section summaries of one source (an article, paper, book chapter, meeting
note) so they can be searched with search_text and cited, each with its heading or locator in
the original and the Terms it is about. The full original stays in the Obsidian vault: point
the source at a note already there (source.original), or pass source.original_text or
source.original_file to keep it there. Keep one idea per passage. A passage with the same text
from the same source updates instead of duplicating; delete_ids removes passages. When the
document changed, save the source again (same uri or id) with the new original and call this
with replace=true and every passage of the new version: unchanged passages keep their ids, and
get_source shows the records and concepts to check next. Use add_records for countable facts
and save_concept for definitions.
- **search_text** — Search the text of the knowledge store: passages, Term definitions and bodies, and sources.
Returns ranked hits (bm25) with the matching words in [brackets], the heading or locator, the
Terms each passage is about and a [[link]] to the original in Obsidian. Words match with their
Korean particles (기억 finds 기억을) and inside compounds. Also returns the FTS query and a SQL
example, so you can combine the search with records, relations and sources in one run_sql:
passages_fts MATCH ... joined to passages, passage_terms, terms, term_relations and sources.
Read-only.
- **get_source** — Show one source (by id or part of its title) with its summary, content and the path of its
original in the Obsidian vault, and everything stored from it: records per entity, concepts,
relations and passages. Use it to cite where an answer came from or to review what a document
contributed; use search_text to find sources by their words. Read-only.
- **list_terms** — List every Term of a datasource (the index): entities and concepts with their one-line definition,
status, synonyms, record and relation counts, and which concepts are still empty. Use it to
browse or before adding knowledge, to reuse Terms instead of creating near-duplicates; use
search_ontology to find Terms by words and get_term for one Term's full detail. Read-only.
- **recent_changes** — List recent changes across the ontology and knowledge store (the log), newest first: Terms, records,
concepts, relationships and SQL attributes added, changed, certified or deleted. Use it to
answer 'what did I add lately' or to review a session's work. Read-only.
- **export_wiki** — Write the ontology (by default the knowledge store) as Obsidian pages: one page per Term with
synonyms as aliases, relations as [[links]] and its passages, one per source with a link to
the original and its passages, plus index.md and log.md. The knowledge store goes to the
vault (AUTO_ONTOLOGY_VAULT/auto-ontology, or ~/.auto-ontology-mcp/wiki/knowledge), other
datasources to ~/.auto-ontology-mcp/wiki/<datasource>. Re-exporting rewrites and prunes only
pages it generated; originals and other files are never touched. Edits made in Obsidian are
not read back. Use export_ontology for a single YAML/JSON document.
- **search_ontology** — Find Terms, concepts (including their bodies and relations), mapped columns, SQL attributes,
glossary entries, verified example questions, sources and unmodeled tables by words. In the
knowledge store it also matches records by their stored text ('value' hits) and adds the top
full-text hits from passages, bodies and sources ('text_hits'). Use it to locate things by name
or topic; use search_text to search the text itself, list_terms to browse everything and
get_term for full detail. Matching is lexical, not semantic: use the schema's vocabulary, try
synonyms and translate. Read-only.
- **get_term** — Return one Term in full: definition, status, synonyms, body, mapped columns with sample values and
formats, SQL attributes, related Terms with join conditions, typed relations and sources,
plus record counts for knowledge entities. Accepts a name, synonym or id; if nothing
matches, the error lists the closest Terms. Use it to answer 'what is X' and before writing
SQL about X; use search_ontology when you do not know the name and describe_table for a
physical table. Read-only.
- **describe_table** — Return one physical table: every column (including ones no Term maps), keys, junction status, the
Terms and attributes on it, its relationships and SQL attributes. Use it to inspect a
table's structure; use get_term for business meaning and get_source for
provenance. Fails with suggestions if the table name is unknown. Read-only.
- **find_join_path** — Return the shortest chain of accepted relationships between two Terms or tables, with ON conditions,
a ready FROM/JOIN clause, fan-out warnings and other roles for the same hop (billing vs
delivery city). Use it when you need one specific route; get_query_context already includes
the path for a set of Terms. Reports found=false when no chain exists. Read-only.
- **check_answerable** — Check, before any SQL, whether the ontology covers each entity of the question. Extract 1-5 entity
phrases yourself and pass them; each comes back covered (by a Term, attribute or SQL
attribute), covered_by_value (a name stored in the data), weak, or not covered, with an
overall verdict and the next step. When something material is not covered, tell the user
instead of substituting a similar measure. Read-only and fast; use get_query_context next.
- **get_query_context** — Return what you need to write the SQL for a set of Terms: qualified tables, mapped columns with
samples and formats, SQL attributes, the join path connecting them (with a ready FROM/JOIN
clause and role notes), verified example queries, glossary and the dialect's SQL rules. Call
it after check_answerable with the Terms you will use. Unknown Terms are listed under
unresolved with suggestions; if none resolve, it fails. Read-only.
- **lookup_values** — Return real values stored in a column ('table.column'): matches for a case-insensitive text, close
spellings when nothing matches, or the most common values with their counts. Use it to
ground literal filters (a place, product or status) before writing them into SQL. Read-only.
- **validate_sql** — Check one query without returning rows: read-only guard, unknown tables or columns (with the
ontology's name for them), joins the ontology does not know or that use a non-default role,
near-miss literals, percent-vs-fraction thresholds, one-to-many fan-out under SUM/AVG/COUNT,
and a dry run; also which Terms it relies on and whether they are certified. Use it before
run_sql and fix every error. Read-only.
- **run_sql** — Execute one read-only SELECT and return columns, rows, row_count and truncated, plus the Terms it
used and warnings. Use it after validate_sql. Writes, DDL, multiple statements and tables
outside the catalog are refused, and the connection itself is read-only. The query is logged
with the question for provenance. Show the SQL with the answer and say when rows are
truncated.
- **save_example_query** — Store a question and SQL pair the user confirmed as correct. Later, get_query_context offers it for
similar questions and suggest_sql_attributes mines it. Saving the same question again
replaces its SQL. The SQL must validate, or nothing is saved.
- **export_ontology** — Return a datasource's whole semantic layer as one YAML or JSON document: tables, relationships,
Terms with column mappings, SQL attributes, concepts and typed relations, glossary and
example queries. Use it for review, backup or moving the ontology; records in the knowledge
store are not included. Use export_wiki for an Obsidian view. Read-only.
- **import_ontology** — Apply a document produced by export_ontology to a datasource that has been scanned, matching tables
and columns by name. Existing items with the same names are updated; a table's Terms are
replaced as in save_table_terms. Items that fail (missing tables or columns, invalid SQL)
are skipped and listed while the rest is applied, so the result can be partial. Knowledge
entities are recreated empty when their tables are missing; records are not imported.
- **search** — Search Terms, tables and sources across all datasources and return ids for fetch. Intended for
ChatGPT connectors and deep research; other clients should prefer search_ontology.
Read-only.
- **fetch** — Return the full text of one document returned by search: a Term (definition, body, attributes, SQL
attributes, relations, sources), a table, or a source. Read-only.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "auto-ontology-mcp": {
    "command": "uvx",
    "args": ["--from","git+https://github.com/gogoymh/auto-ontology-mcp","auto-ontology-mcp"]
  }
}
```

## Documentation

## What auto-ontology-mcp does

auto-ontology-mcp connects MCP clients to two related workflows: ontology-guided database analysis and a personal knowledge base. For structured data, the model can inspect a database, build business Terms, review joins, identify value representations, and ask questions using SQL that the server checks against the ontology and stored data.

The knowledge-base workflow accepts material such as receipts, statements, research papers, book notes, screenshots, and other documents. Extracted facts are stored as records, ideas become linked concepts, useful passages are indexed for full-text search, and source information is retained.

## How it works

Language tasks such as reading, extraction, naming, judgment, and SQL drafting are performed by the model in the connected MCP client. The server handles deterministic operations including schema extraction, data profiling, key inference, ontology validation, storage, and read-only query execution. It stores its local working data in SQLite files and does not require an LLM endpoint or LLM API key.

For database questions, the client can check whether requested concepts are covered, retrieve relevant query context, find valid join paths, validate a draft query, and execute the corrected SQL. Validation can catch incorrect joins, mismatched stored values, percentage-scale mistakes, fan-out caused by one-to-many relationships, and questions that the available data cannot answer.

For documents, the client can preserve the original text, save passages and concepts, associate relationships and source locations, and search the resulting text index. The `export_wiki` capability writes the knowledge base to an Obsidian vault with aliases, wikilinks, and graph-view relationships.

## Setup and configuration

The project requires Python 3.12 or newer and supports both stdio and streamable HTTP MCP transports. Connect it to an MCP client that supports one of those transports, then point the workflow at the database or knowledge-base material you want the client to process. No model provider endpoint or LLM API key is needed because language operations run through the connected client.

The `auto-ontology-mcp demo` command creates a fictional retail example with a synthetic database, sample knowledge-base documents, and questions combining both sources. It is useful for checking the database and document workflows before using personal data.

## Tools and capabilities

- Check whether requested entities or metrics are answerable with `check_answerable`.
- Retrieve ontology terms, join paths, role notes, and related query guidance with `get_query_context` and `find_join_path`.
- Review generated SQL against known relationships and data values using `validate_sql`.
- Execute read-only SQL with `run_sql`.
- Save source passages and concepts through `save_passages` and `save_concept`.
- Search indexed passages with `search_text` and export the knowledge base with `export_wiki`.

Ontology relationships can distinguish roles such as billing and delivery locations, while draft Terms remain identifiable as unreviewed. Knowledge-base records preserve links back to their originating documents and passages.

## Limitations and notes

The system can identify when a requested measure is not covered, but it cannot calculate a metric absent from the connected data, such as return on ad spend without advertising spend. Generated Terms may remain drafts until reviewed, so their definitions should be treated accordingly.

The server performs read-only SQL execution. Its local storage is based on SQLite, while original knowledge-base documents are kept in an Obsidian vault rather than being reduced to only extracted facts or passages.

_Full upstream README: https://allmcps.com/mcp/auto-ontology-mcp/readme_