nlqueries/nlqueries
🐍 🏠 - Natural language to validated SQL engine with multi-connector support (PostgreSQL, MySQL, Snowflake, BigQuery, DuckDB), document QA, semantic caching, and self-hosted MCP server.
Quick Install
{
"mcpServers": {
"nlqueries-nlqueries": {
"command": "npx",
"args": [
"-y",
"nlqueries-nlqueries"
]
}
}
}Using an AI coding agent (Claude Code, Cursor, etc.)? Copy a ready-made prompt that tells it to fetch the setup instructions and install this server for you.
Documentation Overview
nlqueries-core
NLQueries Core turns plain-English questions into validated SQL, builds a self-updating YAML knowledge base from your schema and query history, and exposes everything as an MCP server your AI assistant can call directly. It also answers questions from your documents (PDF, Word, Excel, Notion, Confluence) and can blend both in a single hybrid answer.
Website & docs: nlqueries.com
Features
| Capability | Description |
|---|---|
| Database connectors | PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB — plus a generic SQLAlchemy connector for any other SQLAlchemy-reachable database, driven by a connection URL |
| Document connectors | PDF, Word, Excel, Notion, Confluence — ask questions over ingested documents with citations |
| Query pipeline | Filter, cluster, and parameterize query history into reusable QueryCapsule templates |
| Knowledge base | Auto-generated YAML schema + capsule file, with coverage reporting via kb-stats |
| Multi-agent orchestration | Routes each question to a SQL agent, document agent, or both in parallel (hybrid) |
| Conversational follow-ups | Carries context across questions so a follow-up like "and by region?" resolves against the previous query — on by default in nlqueries query, reset with --new-session |
| Semantic cache | Returns previously-answered similar questions in under 50 ms, no LLM or DB round-trip |
| Embedding daemon | Keeps the embedding model resident in memory — ~10 ms per call instead of ~9 s |
| LLM client | Anthropic, OpenAI, or any LiteLLM-supported provider |
| MCP server | Query execution and schema/knowledge lookup exposed as MCP tools for Claude, Cursor, etc. |
| CLI | nlqueries (or the shorter nlq alias) — connect, build, query, and inspect from your terminal |
See docs/architecture.md for how these pieces fit together.
Quickstart
Prerequisite: Python 3.11+.
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 at least one LLM key:
ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY=sk-...
Then start the stack:
docker compose up
This pulls nlqueries/core:latest 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
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
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
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.
Documentation
| Doc | Covers |
|---|---|
| docs/getting-started.md | Step-by-step setup and your first query |
| docs/cli-reference.md | Every command and flag |
| docs/connectors.md | Database and document connector setup, per-connector notes and caveats |
| docs/configuration.md | Environment variables |
| docs/troubleshooting.md | Common warnings and errors explained |
| docs/qdrant-setup.md | Setting up Qdrant (required for embeddings, semantic cache, document search) |
| docs/architecture.md | Module layout and request flow |
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 — each release converts to Apache 2.0 four years after its release date.