NLQueries
OfficialThis MCP server lets AI assistants discover NLQueries agents, inspect schemas, ask natural-language questions that produce validated SQL or cited document answers, and manage feedback, cache, history, and health.
List available agents and registered database connectors.
Retrieve an agent's tables, columns, types, and foreign keys.
Ask natural-language questions; get generated SQL, answers, and source citations.
Request provenance/explain output and plain-English SQL paraphrases.
Submit thumbs-up/down feedback, optionally with corrected SQL.
Check connectivity to the LLM, Qdrant, embedding daemon, and config.
Invalidate an agent's semantic cache and view cache statistics.
Inspect recent query history and feedback ratings.
Allows querying Amazon Redshift databases using natural language.
Allows querying Confluence documents and retrieving answers with citations.
Allows querying DuckDB databases using natural language.
Allows querying MySQL databases using natural language.
Allows querying Notion documents and retrieving answers with citations.
Uses OpenAI's language models to process natural language queries and generate SQL.
Allows querying PostgreSQL databases using natural language.
Allows querying Snowflake databases using natural language.
nlqueries-core
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.
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
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 ( |
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 |
Knowledge base | Auto-generated YAML schema + capsule file, with coverage reporting via |
Document Q&A |
|
Conversational follow-ups | Carries context across questions so a follow-up like "and by region?" resolves against the previous query — on by default in |
Semantic cache | Recognises a question |
Embedding daemon | Keeps the embedding model resident in memory — ~10 ms per call instead of ~9 s |
Feedback loop | Rate an answer with |
Regression checks |
|
dbt import |
|
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 |
|
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.ymlCreate 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 32The 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 upThis 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 healthThe 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 healthOptional 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 syncPostgreSQL 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 healthSee 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 contextFollow-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 |
Step-by-step setup and your first query | |
Every command and flag | |
Database and document connector setup, per-connector notes and caveats | |
Environment variables | |
Anthropic, OpenAI, Amazon Bedrock and DeepSeek: the settings for each, effort and thinking, prompt caching, token usage | |
Common warnings and errors explained | |
Setting up Qdrant (required for embeddings, semantic cache, document search) | |
Connecting Claude Desktop, Cursor and remote MCP clients | |
Authenticating the MCP server — required to serve it over a network | |
Module layout and request flow | |
The read-only role to grant per engine, and exactly what each connector does and does not enforce | |
Logs, audit events, OpenTelemetry spans and metrics, and health checks | |
The hashed lock file the image builds from, the digest-pinned base image, and how to regenerate both | |
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 toolsget_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceA production-ready MCP server that transforms natural language into safe, executable SQL queries with multi-database support and intelligent schema analysis.1-
- AlicenseNot gradedqualityDmaintenanceA unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.GPL 3.0
- AlicenseNot gradedqualityDmaintenanceMCP server for SQL analytics on DuckDB and MotherDuck databases, enabling AI assistants and IDEs to query data via natural language.1MIT

Atlas MCPofficial
AlicenseNot gradedqualityAmaintenanceEnables natural language querying of SQL databases and REST APIs through the MCP protocol, grounded in a semantic layer.188 npm1AGPL 3.0