Neocarta

An end-to-end library for building a semantic layer in Neo4j — giving AI agents systemic understanding of how your data is organized, what it means, and where it lives.

Note: This library is not a Neo4j product. It is a Neo4j Labs project supported by the Neo4j field team.

What it is

Neocarta builds a semantic layer in Neo4j from your data sources and serves it to your agents through an MCP server. The graph unifies more than raw schema — it brings together:

• Schema metadata — tables, columns, foreign keys, and sample values
• Business glossary — terms and categories linked to the columns and tables they describe
• Metrics — governed metric definitions and their expressions
• Query history — real queries and the tables and columns they touch

…with more on the way. Across a growing set of database types, only the metadata crosses into Neo4j; your data stays in the source.

This gives agents systemic familiarity with the data landscape — what data exists, what it means, how it joins, and which database holds it. Agents use the graph to discover insights, ground their answers, and route queries to the right database, making Text2Query, query routing, and data discovery reliable.

Quickstart

1. Ingest — read your source's schema into the semantic graph (your data stays in the source). Use the Python library or the CLI.

Python — this is the BigQuery connector example:

import os
from google.cloud import bigquery
from neo4j import GraphDatabase
from neocarta import NodeLabel as nl
from neocarta.connectors.bigquery import BigQuerySchemaConnector
from neocarta.enrichment.embeddings import LiteLLMEmbeddingsConnector

driver = GraphDatabase.driver(
    os.getenv("NEO4J_URI"),
    auth=(os.getenv("NEO4J_USERNAME"), os.getenv("NEO4J_PASSWORD")),
)
client = bigquery.Client(project=os.getenv("GCP_PROJECT_ID"))

# Extract, transform, and load BigQuery schema metadata into Neo4j
BigQuerySchemaConnector(
    client=client,
    project_id=os.getenv("GCP_PROJECT_ID"),
    neo4j_driver=driver,
).ingest(dataset_id=os.getenv("BIGQUERY_DATASET_ID"))

# Optional: generate embeddings to turn on semantic table/column search
LiteLLMEmbeddingsConnector(
    neo4j_driver=driver,
    embedding_model="text-embedding-3-small",
).run(node_labels=[nl.DATABASE, nl.SCHEMA, nl.TABLE, nl.COLUMN])

CLI — the same ingest without writing Python (--embeddings is optional):

pip install "neocarta[cli]"
# reads NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD / OPENAI_API_KEY from the environment or a .env file
neocarta bigquery schema --project-id my-proj --dataset-id sales --embeddings

See the Neocarta CLI section for the full command set.

2. Serve — expose the graph to your agent as tools:

pip install "neocarta[mcp]"
# reads NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD from the environment or a .env file
neocarta-mcp           # or, from the unified CLI: neocarta mcp serve

The server gives the agent retrieval tools — `list_s