nlqueries-core

NLQueries Core is an open-source natural language to SQL engine — see nlqueries.com. It turns plain-English questions into validated SQL, builds a YAML knowledge base from your schema and query history (rebuilt whenever you re-run export-kb), and exposes everything as an MCP server your AI assistant can call directly. It also answers questions from your documents (PDF, Word, Excel, Markdown, plain text, Notion, Confluence), with citations.

Links

• Website — nlqueries.com
• Documentation — nlqueries.com/docs/
• Getting started — nlqueries.com/docs/getting-started
• Supported databases — nlqueries.com/databases/
• PyPI — nlqueries-core
• Docker Hub — nlqueries/core

Features

See docs/architecture.md (or read online) for how these pieces fit together.

Quickstart

Prerequisite: Python 3.11–3.14.

Option A — Docker (recommended)

Pulls the published nlqueries/core image from Docker Hub — no clone required, just the compose file:

curl -O https://raw.githubusercontent.com/nlqueries/nlqueries/main/docker-compose.yml

Create a .env file next to it with one LLM key, a Qdrant key and an MCP token. All three are required — compose refuses to start without QDRANT_API_KEY or NLQ_MCP_STATIC_TOKEN:

ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY=sk-...
QDRANT_API_KEY=...         # any random secret: openssl rand -hex 32
NLQ_MCP_STATIC_TOKEN=...   # another one: openssl rand -hex 32

The MCP server is reachable over the network, so it requires that token: an MCP client connects to http://localhost:8080/sse and sends Authorization: Bearer <your NLQ_MCP_STATIC_TOKEN>. The token has full access. To give different people different access, see docs/mcp-authentication.md.

Then start the stack:

docker compose up

This pulls nlqueries/core:0.3.0 and starts it alongside Qdrant (:6333), with the MCP server on :8080. Run CLI commands against the running stack from a second terminal:

docker exec -it nlqueries-core nlqueries health

The image includes the PostgreSQL, SQLite, Snowflake, BigQuery and DuckDB drivers. It does not include the MySQL, Redshift or SQL Server drivers, or the docs and wiki extras (PDF / Word / Excel ingestion, Notion / Confluence sync); for those, install with pip (Option B) and add the extra.

Option B — pip install

pip install nlqueries-core
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
nlqueries health

Optional extras for specific connectors:

pip install "nlqueries-core[mysql]"      # MySQL (driver for the generic connector)
pip install "nlqueries-core[snowflake]"  # Snowflake
pip install "nlqueries-core[bigquery]"   # Google BigQuery
pip install "nlqueries-core[redshift]"   # Amazon Redshift
pip install "nlqueries-core[mssql]"      # SQL Server / Azure SQL
pip install "nlqueries-core[duckdb]"     # DuckDB
pip install "nlqueries-core[docs]"       # PDF / Word / Excel ingestion
pip install "nlqueries-core[wiki]"       # Notion / Confluence sync

PostgreSQL and SQLite need no extra. The generic sqlalchemy connector needs whichever driver its URL names.

Option C — Clone and install from source

No Docker required — for contributing, or to run against unreleased changes:

git clone https://github.com/nlqueries/nlqueries.git
cd nlqueries
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
nlqueries health

See CONTRIBUTING.md for linting and test commands.

First query

nlqueries connect postgres --host localhost --database mydb --user alice --password secret --alias dev
nlqueries process-history dev --days 30 --annotate
nlqueries export-kb dev
nlqueries query dev "How many orders shipped last month?"
nlqueries query dev "and how many were returned?"   # follow-up — keeps prior context

Follow-up context is on by default; pass --new-session to start fresh or --no-session to disable it for a one-off question.

Full walkthrough: docs/getting-started.md (or read online).

Documentation

Contributing

See CONTRIBUTING.md. All contributors must sign the CLA before a PR can be merged — see CONTRIBUTOR_LICENSE_AGREEMENT.md.

License

Business Source License 1.1 — converting to Apache 2.0 no later than June 4, 2030. The licence sets that date and also converts each version on the fourth anniversary of its own first publication, whichever comes first, so a version first published before June 4, 2026 converts on its own anniversary, ahead of the fixed date.

Until then the licence grants production use, including commercially and self-hosted, with one carve-out: you may not offer NLQueries Core to third parties as a hosted or managed service. Individual and non-commercial self-hosted deployments are unrestricted. LICENSE is the authority; this paragraph is a summary.