Installing Neocarta and its optional extras

Neocarta is distributed as a single PyPI package (neocarta) with a modular set of optional extras. The core install is all you need to run connectors and generate embeddings in Python. Add [cli] for the command-line tool, [mcp] for the MCP server, [performance] for Rust-accelerated Neo4j writes, and [databricks] for the Databricks governed-tags connector. Extras can be combined freely.

Core install

Neocarta requires Python 3.10 or higher.

pip install neocarta

Optional extras

python-dotenv is a core dependency of Neocarta. Any .env file in the working directory is loaded automatically — you do not need to call load_dotenv() explicitly when using the CLI.

Extra	Install command	What it adds
`cli`	`pip install "neocarta[cli]"`	The `neocarta` Click-based CLI — `neocarta bigquery schema`, `neocarta csv ingest`, `neocarta tool list-schemas`, and all other noun-verb commands. Also needed for `neocarta mcp serve`.
`mcp`	`pip install "neocarta[mcp]"`	The `neocarta-mcp` MCP server built on FastMCP. Exposes the semantic graph as retrieval tools over stdio.
`performance`	`pip install "neocarta[performance]"`	`neo4j-rust-ext` — replaces the pure-Python serialisation layer of the Neo4j Python driver with a compiled Rust extension. Delivers 60–90% faster throughput for bulk loads. Requires Python 3.11+.
`databricks`	`pip install "neocarta[databricks]"`	The Databricks SDK (`databricks-sdk`), required by the Databricks governed-tags connector.

Extras can be combined in a single install command:

pip install "neocarta[cli,mcp]"

pip install "neocarta[cli,mcp,performance]"

The [performance] extra requires Python 3.11 or higher because neo4j-rust-ext is a compiled native extension. Installing it under Python 3.10 will fail at build time. All other extras are compatible with Python 3.10+.

Neo4j setup

Neocarta requires a running Neo4j instance. Choose the option that fits your workflow:

AuraDB (cloud)
Neo4j Desktop
Docker

Neo4j AuraDB is a fully-managed cloud service. The free tier gives you a persistent instance at no cost — no credit card required.

Go to console.neo4j.io and create a free instance.
Copy the Connection URI (format: neo4j+s://xxxxxxxx.databases.neo4j.io).
Note the auto-generated password shown at creation time.
Add both to your .env file (see Environment variables below).

Neo4j Desktop is a local GUI application for managing Neo4j instances during development.

Download and install Neo4j Desktop.
Create a new local DBMS and start it.
Your URI will be bolt://localhost:7687.
The default username is neo4j; set your password on first launch.

The official Docker image is the lightest option for a local instance — no installer, no GUI.

docker run \
  -p 7474:7474 \
  -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:latest

7474 — Neo4j Browser (HTTP)
7687 — Bolt protocol (used by the Python driver)

After the container starts, open http://localhost:7474 to verify the instance is running. Your URI for .env is bolt://localhost:7687.

Environment variables

All Neocarta connectors and the MCP server read configuration from environment variables. The recommended approach is a .env file in your project root — it is loaded automatically at runtime.

Copy the block below into a .env file and fill in the values for your environment. Variables marked as optional can be omitted if you are not using the corresponding feature.

.env

# ── Neo4j connection ────────────────────────────────────────────────────────
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

# ── Embedding provider ──────────────────────────────────────────────────────
# Required if you want to generate or query vector embeddings.
OPENAI_API_KEY=sk-...

# LiteLLM model identifier (OpenAI, Gemini, Cohere, Bedrock, Azure, etc.)
EMBEDDING_MODEL=text-embedding-3-small

# Optional: vector dimension for models that support truncation (e.g. OpenAI
# text-embedding-3-*). Leave unset to auto-detect from the model.
# EMBEDDING_DIMENSIONS=1536

# Optional: number of nodes per embedding batch during CLI ingest (default: 100).
# EMBEDDING_BATCH_SIZE=100

# ── BigQuery / GCP ──────────────────────────────────────────────────────────
# Required for BigQuery and Dataplex connectors.
GCP_PROJECT_ID=my-gcp-project
BIGQUERY_DATASET_ID=my_dataset

Full variable reference

Variable	Required for	Description
`NEO4J_URI`	All connectors	Bolt or `neo4j+s://` URI of your Neo4j instance
`NEO4J_USERNAME`	All connectors	Neo4j username (default: `neo4j`)
`NEO4J_PASSWORD`	All connectors	Neo4j password
`NEO4J_DATABASE`	All connectors	Target database name (default: `neo4j`)
`OPENAI_API_KEY`	Embeddings (OpenAI)	OpenAI API key for embedding generation
`EMBEDDING_MODEL`	Embeddings	LiteLLM model identifier, e.g. `text-embedding-3-small`
`EMBEDDING_DIMENSIONS`	Embeddings (optional)	Vector dimension override for truncation-capable models
`EMBEDDING_BATCH_SIZE`	Embeddings (optional)	Nodes per batch during ingest (default `100`)
`GCP_PROJECT_ID`	BigQuery, Dataplex	GCP project ID
`BIGQUERY_DATASET_ID`	BigQuery connector	BigQuery dataset to ingest

For connector-specific variables (JDBC, Unity Catalog, Databricks, Dataplex), see the .env.example file in the Neocarta repository and the individual connector READMEs.

Get Started

Connectors

Enrichment

MCP Server

CLI Reference

Installing Neocarta and its optional extras

Core install

Optional extras

Neo4j setup

Environment variables

Full variable reference

Build docs developers (and LLMs) love

Get Started

Connectors

Enrichment

MCP Server

CLI Reference

Documentation Index

​Core install

​Optional extras

​Neo4j setup

​Environment variables

​Full variable reference

Build docs developers (and LLMs) love

Core install

Optional extras

Neo4j setup

Environment variables

Full variable reference