Skip to main content
Glama
NLQueries

NLQueries

Official
by nlqueries

nlqueries-core

CI PyPI Python License: BSL 1.1 Visitors

NLQueries Core is a self-hosted 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.


Related MCP server: Legion Database MCP Server

Features

Capability

Description

Database connectors

PostgreSQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB, SQLite — plus a generic SQLAlchemy connector, driven by a connection URL, for MySQL (connect mysql) and any other SQLAlchemy-reachable database

Document connectors

PDF, Word, Excel, Markdown, plain text, 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

Document Q&A

doc-ingest (or doc-sync-notion / doc-sync-confluence) chunks, embeds and stores a source in Qdrant; doc-ask answers from it with citations

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

Recognises a question query or the MCP query tool has answered before, by meaning, and skips the LLM: it replays the stored answer and runs the stored SQL again so the rows are current (not with --no-execute). ask does not use it. Needs Qdrant

Embedding daemon

Keeps the embedding model resident in memory — ~10 ms per call instead of ~9 s

Feedback loop

Rate an answer with feedback, review with feedback-stats, and promote-feedback the thumbs-up ones — their SQL is re-validated against the current schema and blended into later prompts as verified examples

Regression checks

eval re-asks the agent's own mined capsules — and a golden question set too, with --golden — then checks the generated SQL parses and references only tables the agent knows

dbt import

import-dbt merges dbt model and column descriptions into the knowledge base

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 (or read online) for how these pieces fit together.


Quickstart

Prerequisite: Python 3.11–3.14.

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.4.1 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

Doc

Covers

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

Step-by-step setup and your first query

docs/cli-reference.md (or read online)

Every command and flag

docs/connectors.md (or read online)

Database and document connector setup, per-connector notes and caveats

docs/configuration.md (or read online)

Environment variables

docs/llm-providers.md

Anthropic, OpenAI, Amazon Bedrock and DeepSeek: the settings for each, effort and thinking, prompt caching, token usage

docs/troubleshooting.md (or read online)

Common warnings and errors explained

docs/qdrant-setup.md (or read online)

Setting up Qdrant (required for embeddings, semantic cache, document search)

docs/mcp-clients.md

Connecting Claude Desktop, Cursor and remote MCP clients

docs/mcp-authentication.md (or read online)

Authenticating the MCP server — required to serve it over a network

docs/architecture.md (or read online)

Module layout and request flow

docs/database-hardening.md (or read online)

The read-only role to grant per engine, and exactly what each connector does and does not enforce

docs/observability.md

Logs, audit events, OpenTelemetry spans and metrics, and health checks

docs/dependency-locking.md (or read online)

The hashed lock file the image builds from, the digest-pinned base image, and how to regenerate both

docs/contributing.md (or read online)

What a new connector has to implement, and what to open an issue about first


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.

Available Tools

9 tools
get_agent_schemaA

Return the schema for an agent: tables, columns, types, and foreign keys.

Reads the agent's YAML knowledge base and formats it compactly so you can
inspect which tables and columns are available before formulating a
question. A table whose column list is partial carries a note saying so.

Args:
    agent_id: Agent ID from list_agents().

Returns:
    Formatted schema string, or an error message if the agent is not found.

Inputs: agent_id (required). Returns: result

get_cache_statsA

Return cache statistics for an agent.

Reports the number of cached entries and the Qdrant collection name
used for this agent's semantic cache.

Args:
    agent_id: Agent to inspect.

Returns:
    Formatted stats string.

Inputs: agent_id (required). Returns: result

get_query_historyA

Return recent queries and their feedback ratings for an agent.

Args:
    agent_id: Agent to look up.
    limit:    Maximum number of records to return (default: 20, max: 200).

Returns:
    Formatted history string, newest first.

Inputs: agent_id (required), limit. Returns: result

healthA

Check connectivity to all NLQueries dependencies.

Runs four checks in sequence:
- LLM: reports the configured provider and model. Sends a real completion
  only when *probe_llm* is true.
- Qdrant: hits the /healthz endpoint.
- Embed daemon: probes the local embedding server.
- Config: verifies KB_PATH exists and required env vars are set.

Args:
    probe_llm: Spend a token on a live round-trip to the model. Off by
        default: this tool is reachable without credentials, and a health
        check that costs money is a way to bill someone for asking whether
        their server is up. Off, the LLM line reports configuration; on, it
        reports latency and a working key.

Returns:
    A formatted status report string.

Inputs: probe_llm. Returns: result

invalidate_cacheA

Drop the entire semantic cache for an agent.

Use this after a schema change or data refresh to force fresh SQL
generation on the next query.  The cache is rebuilt automatically
as new queries arrive.

Args:
    agent_id: Agent whose cache should be cleared.

Returns:
    Confirmation string.

Inputs: agent_id (required). Returns: result

list_agentsA

Return the IDs of all agents available on this NLQueries installation.

An agent is available when its YAML knowledge-base file exists in KB_PATH
(default: ~/.nlqueries/knowledge_base/).  Run ``nlqueries export-kb`` to
create an agent from a registered connector.

Returns:
    Sorted list of agent ID strings, e.g. ["sales", "support"].
    Empty list when no agents have been exported yet.

Inputs: no named parameters. Returns: result

list_connectorsA

List registered database connectors and their types.

Returns connectors registered via ``nlqueries connect``.  Passwords and
full connection URLs are redacted for safety.

Returns:
    Formatted list of connector IDs and their db-types, or a message
    when no connectors are registered.

Inputs: no named parameters. Returns: result

queryA

Ask a natural-language question to an NLQueries agent.

The agent translates the question into SQL and runs it. An agent that lists
document sources (`nlqueries agent docs add`) may instead answer from those
documents, or from both, as the question needs. The answer comes with the
generated SQL and any source citations.

Args:
    question:  The natural-language question, e.g. "Total revenue by region
               last quarter?"
    agent_id:  Agent to query — use list_agents() to discover available IDs.
    dialect:   Ignored, and kept so clients that send it keep working. The
               SQL dialect is the one of the database the agent's
               connector points at.
    explain:   When true, append an answer-provenance summary (route,
               cache hit/miss, knowledge injected, checks, timings).
    paraphrase: When true, append a deterministic plain-English rendering of
               the generated SQL (no LLM), so you can confirm what it does.

Returns:
    Formatted string containing the natural-language answer, generated SQL
    (for SQL/hybrid agents), and source citations (for document/hybrid agents).
    Includes per-query latency and agent-type metadata.

Inputs: agent_id (required), question (required), dialect, explain, +1 more. Returns: result

submit_feedbackA

Record user feedback for a query result.

Feedback is stored in ~/.nlqueries/feedback/<agent_id>.jsonl. A thumbs-up
can become a verified example through ``nlqueries promote-feedback``, and a
correction an example query through ``nlqueries export-kb``; feedback sent
here is used only when an operator includes it with ``--include-anonymous``.

Args:
    question:      The question that was asked.
    agent_id:      The agent that answered it.
    generated_sql: The SQL that was generated (copy from the query result).
    rating:        ``"up"`` (correct answer) or ``"down"`` (wrong answer).
    corrected_sql: Optional corrected SQL when rating is ``"down"``.

Returns:
    Confirmation string, or an error message.

Inputs: rating (required), agent_id (required), question (required), generated_sql (required), +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource or action: asking questions, inspecting schema, listing agents/connectors, checking health, managing cache, viewing history, and submitting feedback. The only superficially related pairs, such as get_cache_stats vs. invalidate_cache and get_query_history vs. submit_feedback, are separated by read-vs-write or stats-vs-record semantics. An agent should reliably select the correct tool.

    Naming Consistency4/5

    Seven of nine tools follow a predictable snake_case verb_noun pattern, e.g. get_agent_schema, list_agents, invalidate_cache, and submit_feedback. The bare names query and health slightly deviate from that pattern, but the set remains readable and mostly consistent.

    Tool Count5/5

    Nine tools is well-scoped for the server's purpose: one core query tool plus focused introspection, cache, history, feedback, and health operations. Each tool has a clear reason to exist and none feels redundant.

    Completeness4/5

    The surface covers the core NLQueries workflow: discovering agents/connectors, inspecting schema, asking questions, reviewing history, submitting feedback, managing cache, and checking dependencies. Minor lifecycle gaps remain, such as creating/deleting agents or connectors directly, but the descriptions indicate those are handled via the CLI rather than MCP.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      F
      maintenance
      A production-ready MCP server that transforms natural language into safe, executable SQL queries with multi-database support and intelligent schema analysis.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for SQL analytics on DuckDB and MotherDuck databases, enabling AI assistants and IDEs to query data via natural language.
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables natural language querying of SQL databases and REST APIs through the MCP protocol, grounded in a semantic layer.
      188 npm
      1
      AGPL 3.0