What document types can it query?

It supports PDF, Word, Excel, Notion, and Confluence documents for question answering with citations.

How does it handle conversational queries?

It maintains context across questions by default, allowing follow-ups to reference prior queries; this can be reset or disabled per session.

What LLM providers are supported?

Anthropic, OpenAI, and any provider supported by LiteLLM.

How is the MCP server accessed?

The MCP server runs on port 8080 by default and exposes query execution and schema lookup as MCP tools for compatible AI clients.

Nlqueries

Converts natural language questions into validated SQL and document answers with multi-database and document support via an MCP server.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Overview

This server translates plain-English queries into validated SQL statements across multiple SQL databases including PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, and DuckDB. It also supports question answering over ingested documents like PDF, Word, Excel, Notion, and Confluence. The system maintains conversational context for follow-up questions, uses semantic caching for fast repeated queries, and exposes all functionality as MCP tools for integration with AI assistants.

Use cases

Translate natural language questions into SQL queries for various databases

Answer questions over ingested documents alongside database queries

Maintain conversational context for multi-turn querying

Cache and reuse similar query results for low-latency responses

Integrate with AI agents via MCP protocol for hybrid data querying

Key features

Multi-database connectors including PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, D…

Document ingestion and QA for PDF, Word, Excel, Notion, and Confluence

Conversational follow-up support preserving query context

Semantic caching for sub-50ms repeated query responses

Self-hosted MCP server exposing query execution and schema lookup

CLI tools for connection management, query processing, and knowledge base export

Capabilities & Tool Schemas

Inspect callable tools, capabilities, and parameters exposed to AI agents by Nlqueries.

Extracted Tool Capabilities

Multi-database connectors including PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, D…

Document ingestion and QA for PDF, Word, Excel, Notion, and Confluence

Conversational follow-up support preserving query context

Semantic caching for sub-50ms repeated query responses

Self-hosted MCP server exposing query execution and schema lookup

CLI tools for connection management, query processing, and knowledge base export

Documentation Overview

NLQueries

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

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 (or read online) 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:

Terminal

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:

Terminal

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:

Terminal

docker exec -it nlqueries-core nlqueries health

Option B — pip install

Terminal

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

Optional extras for specific connectors:

Terminal

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:

server.ts

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

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 (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/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-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

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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

2d ago

Most recent push to the default branch.

Directory activity

1 views

Config copies, upvotes, and views on AllMCPs.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Nlqueries

PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server/Azure SQL, DuckDB, and any database accessible via SQLAlchemy.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/nlqueries-nlqueries?style=directory)](https://allmcps.com/mcp/nlqueries-nlqueries)

HTML Embed

<a href="https://allmcps.com/mcp/nlqueries-nlqueries"><img src="https://allmcps.com/api/badge/nlqueries-nlqueries?style=directory" alt="Nlqueries on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

11/11 checks healthy over the last 32d

49Quality signal: Fair · 49/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools22/30

Adoption & activity5/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · nlqueries-core (PyPI)

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Nlqueries →Install in Claude Desktop Install in Cursor Install in VS Code

Nlqueries

Converts natural language questions into validated SQL and document answers with multi-database and document support via an MCP server.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Overview

Use cases

Translate natural language questions into SQL queries for various databases

Answer questions over ingested documents alongside database queries

Maintain conversational context for multi-turn querying

Cache and reuse similar query results for low-latency responses

Integrate with AI agents via MCP protocol for hybrid data querying

Key features

Multi-database connectors including PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, D…

Document ingestion and QA for PDF, Word, Excel, Notion, and Confluence

Conversational follow-up support preserving query context

Semantic caching for sub-50ms repeated query responses

Self-hosted MCP server exposing query execution and schema lookup

CLI tools for connection management, query processing, and knowledge base export

Capabilities & Tool Schemas

Inspect callable tools, capabilities, and parameters exposed to AI agents by Nlqueries.

Extracted Tool Capabilities

Multi-database connectors including PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, D…

Document ingestion and QA for PDF, Word, Excel, Notion, and Confluence

Conversational follow-up support preserving query context

Semantic caching for sub-50ms repeated query responses

Self-hosted MCP server exposing query execution and schema lookup

CLI tools for connection management, query processing, and knowledge base export

Documentation Overview

NLQueries

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 (or read online) 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:

Terminal

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:

Terminal

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:

Terminal

docker exec -it nlqueries-core nlqueries health

Option B — pip install

Terminal

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

Optional extras for specific connectors:

Terminal

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:

server.ts

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

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 (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/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-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

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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

2d ago

Most recent push to the default branch.

Directory activity

1 views

Config copies, upvotes, and views on AllMCPs.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Nlqueries

PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server/Azure SQL, DuckDB, and any database accessible via SQLAlchemy.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/nlqueries-nlqueries?style=directory)](https://allmcps.com/mcp/nlqueries-nlqueries)

HTML Embed

<a href="https://allmcps.com/mcp/nlqueries-nlqueries"><img src="https://allmcps.com/api/badge/nlqueries-nlqueries?style=directory" alt="Nlqueries on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

11/11 checks healthy over the last 32d

49Quality signal: Fair · 49/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools22/30

Adoption & activity5/15

Community engagement0/10

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · nlqueries-core (PyPI)

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Nlqueries →Install in Claude Desktop Install in Cursor Install in VS Code

Nlqueries

Quick Install

Client Config & Setup

Overview

Use cases

Key features

Capabilities & Tool Schemas

Documentation Overview

nlqueries-core

Links

Features

Quickstart

Option A — Docker (recommended)

Option B — pip install

Option C — Clone and install from source

First query

Documentation

Contributing

License

Related MCP Servers

Adoption & maintenance

Reviews

Frequently Asked Questions about Nlqueries

AllMCPs Directory Badge

Technical Specs & Signals

Supply-chain signal

Feature Your MCP Server

Own this project?

Share & Embed

Explore more

Nlqueries

Quick Install

Client Config & Setup

Overview

Use cases

Key features

Capabilities & Tool Schemas

Documentation Overview

nlqueries-core

Links

Features

Quickstart

Option A — Docker (recommended)

Option B — pip install

Option C — Clone and install from source

First query

Documentation

Contributing

License

Related MCP Servers

Adoption & maintenance

Reviews

Frequently Asked Questions about Nlqueries

AllMCPs Directory Badge

Technical Specs & Signals

Supply-chain signal

Feature Your MCP Server

Own this project?

Share & Embed

Explore more