# nlqueries/nlqueries [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/nlqueries/nlqueries  
**GitHub Stars:** 3  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nlqueries-nlqueries

## Description
Natural language to validated SQL engine with multi-connector support (PostgreSQL, MySQL, Snowflake, BigQuery, DuckDB), document QA, semantic caching, and self-hosted MCP server.

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

```json
"mcpServers": {
  "nlqueries": {
    "command": "uvx",
    "args": ["nlqueries-core"]
  }
}
```

## Documentation & README

<p align="center">
  <img src="https://raw.githubusercontent.com/nlqueries/nlqueries/HEAD/docs/assets/readme_banner.png" alt="NLQueries" width="1200">
</p>

# nlqueries-core

[![CI](https://github.com/nlqueries/nlqueries/actions/workflows/ci.yml/badge.svg)](https://github.com/nlqueries/nlqueries/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/nlqueries-core)](https://pypi.org/project/nlqueries-core/)
[![Python](https://img.shields.io/pypi/pyversions/nlqueries-core)](https://pypi.org/project/nlqueries-core/)
[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
[![Visitors](https://visitor-badge.laobi.icu/badge?page_id=nlqueries.nlqueries)](https://github.com/nlqueries/nlqueries)

**NLQueries Core** is an open-source natural language to SQL engine — see [nlqueries.com](https://nlqueries.com). It 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.

## Links

- **Website** — [nlqueries.com](https://nlqueries.com)
- **Documentation** — [nlqueries.com/docs/](https://nlqueries.com/docs/)
- **Getting started** — [nlqueries.com/docs/getting-started.html](https://nlqueries.com/docs/getting-started.html)
- **Supported databases** — [nlqueries.com/databases/](https://nlqueries.com/databases/)
- **PyPI** — [nlqueries-core](https://pypi.org/project/nlqueries-core/)
- **Docker Hub** — [nlqueries/core](https://hub.docker.com/r/nlqueries/core)

---

## Features

| Capability | Description |
|---|---|
| **Database connectors** | PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB, SQLite — 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, Amazon Bedrock, 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](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/architecture.md) (or [read online](https://nlqueries.com/docs/architecture.html)) for how these pieces fit together.

---

## Quickstart

**Prerequisite:** Python 3.11+.

### Option A — Docker (recommended)

Pulls the published [`nlqueries/core`](https://hub.docker.com/r/nlqueries/core) image from Docker Hub — no clone required, just the compose file:

```bash
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:

```bash
ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY=sk-...
```

Then start the stack:

```bash
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:

```bash
docker exec -it nlqueries-core nlqueries health
```

### Option B — pip install

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

Optional extras for specific connectors:

```bash
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:

```bash
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](https://github.com/nlqueries/nlqueries/blob/HEAD/CONTRIBUTING.md#development-setup) for linting and test commands.

### First query

```bash
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](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/getting-started.md) (or [read online](https://nlqueries.com/docs/getting-started.html)).

---

## Documentation

| Doc | Covers |
|---|---|
| [docs/getting-started.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/getting-started.md) (or [read online](https://nlqueries.com/docs/getting-started.html)) | Step-by-step setup and your first query |
| [docs/cli-reference.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/cli-reference.md) (or [read online](https://nlqueries.com/docs/cli-reference.html)) | Every command and flag |
| [docs/connectors.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/connectors.md) (or [read online](https://nlqueries.com/docs/connectors.html)) | Database and document connector setup, per-connector notes and caveats |
| [docs/configuration.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/configuration.md) (or [read online](https://nlqueries.com/docs/configuration.html)) | Environment variables |
| [docs/troubleshooting.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/troubleshooting.md) (or [read online](https://nlqueries.com/docs/troubleshooting.html)) | Common warnings and errors explained |
| [docs/qdrant-setup.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/qdrant-setup.md) (or [read online](https://nlqueries.com/docs/qdrant-setup.html)) | Setting up Qdrant (required for embeddings, semantic cache, document search) |
| [docs/mcp-authentication.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/mcp-authentication.md) (or [read online](https://nlqueries.com/docs/mcp-authentication.html)) | Authenticating the MCP server — required to serve it over a network |
| [docs/architecture.md](https://github.com/nlqueries/nlqueries/blob/HEAD/docs/architecture.md) (or [read online](https://nlqueries.com/docs/architecture.html)) | Module layout and request flow |

---

## Contributing

See [CONTRIBUTING.md](https://github.com/nlqueries/nlqueries/blob/HEAD/CONTRIBUTING.md). All contributors must sign the CLA before a PR can be merged — see [CONTRIBUTOR_LICENSE_AGREEMENT.md](https://github.com/nlqueries/nlqueries/blob/HEAD/CONTRIBUTOR_LICENSE_AGREEMENT.md).

---

## License

[Business Source License 1.1](https://github.com/nlqueries/nlqueries/blob/HEAD/LICENSE) — each release converts to Apache 2.0 four years after its release date.