nlp2sql MCP server
Commit Nov 14, 2026Converts natural language questions into SQL queries using a Python DSL with support for multiple LLMs and databases like PostgreSQL and Redshift.
Also known as luiscarbonel1991/nlp2sql
- Stars
- 8
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is nlp2sql MCP?
nlp2sql converts natural language questions into SQL queries using a Python DSL with support for multiple LLMs and databases like PostgreSQL and Redshift.
Summary generated from the project's README
About nlp2sql MCP server
Converting natural language questions into structured SQL queries is the primary function of nlp2sql. This tool is designed for developers and data engineers who need to interface with databases like PostgreSQL and Amazon Redshift using plain English. It utilizes a Python-based domain-specific language to manage the translation process, making it suitable for both simple database schemas and massive data warehouses.
Users interact with the system by connecting to a database URL and providing an API key for supported LLM providers such as OpenAI, Anthropic, or Gemini. The server supports advanced workflows including few-shot examples for better accuracy and semantic context to define specific business metrics, dimensions, and rules. It also features execution modes that allow for generating SQL, validating the output, and automatically repairing queries that fail semantic or execution checks.
To ensure security, the system supports read-only execution modes. For large-scale environments, it employs a hybrid retrieval method using FAISS and TF-IDF to handle complex schemas efficiently.
What you can do with it
- 1Generate SQL from EnglishAsk a question in plain language to receive a corresponding SQL query.
- 2Validate and repair queriesAutomatically check if a generated query is correct and fix it if it fails.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NLP2SQL_DEFAULT_DB_URLOPENAI_API_KEY
| Name | Description | |
|---|---|---|
| NLP2SQL_DEFAULT_DB_URL | — | |
| OPENAI_API_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableluiscarbonel1991/nlp2sql is public and reachablegithub.com/luiscarbonel1991/nlp2sql ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/luiscarbonel1991/nlp2sql ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubnlp2sql
DSL-first natural language to SQL, with pluggable databases and LLM providers
nlp2sql turns a natural language question into SQL through a reusable Python DSL:
await connect(...)await nlp.ask(...)- optional few-shot examples
- optional semantic context
- optional validation and repair
The library is designed for both simple schemas and large warehouses, but all public examples in this repository use the local e-commerce domain shipped with the project itself.
Features
- DSL-first API:
connect()returns anNLP2SQLclient withask(),validate(),explain(), andsuggest() - Business-aware generation: optional
SemanticContextadds canonical tables, metrics, dimensions, rules, and mappings - Execution modes: generate only, generate plus validate, and generate plus validate plus repair
- Read-only execution: queries pass a safety check and run in read-only transactions; connect with a database user that can only read (see SECURITY.md)
- Few-shot examples: pass example lists directly or use an example repository implementation
- Large schema support: FAISS plus TF-IDF hybrid retrieval, schema filters, and disk-backed caches
- Multiple providers: OpenAI, Anthropic, and Gemini built in, or your own
AIProviderPortpassed toQueryGenerationService - Database support: PostgreSQL and Amazon Redshift built in; register a
SchemaRepositoryPortimplementation withRepositoryFactory.register()and passdatabase_type=toconnect()to add another database - Async by default: built for services, APIs, notebooks, and workers
Documentation
| Document | Description |
|---|---|
| Architecture | Runtime flow, services, ports, and diagrams |
| API Reference | Python API, CLI, hooks, and metadata reference |
| Configuration | Environment variables, examples, semantic context, cache behavior |
| Enterprise Guide | Governed usage, scale, and deployment patterns |
| Redshift Support | Redshift-specific notes using public examples |
| Examples | Safe public examples based on the local e-commerce domain |
| Contributing | Contribution guidelines |
Installation
# With UV (recommended)
uv add nlp2sql
# With pip
pip install nlp2sql
# With specific providers
pip install nlp2sql[anthropic,gemini]
pip install nlp2sql[all-providers]
# With embeddings
pip install nlp2sql[embeddings-local]
pip install nlp2sql[embeddings-openai]
Quick Start
1. Set a Provider Key
export OPENAI_API_KEY="your-openai-key"
# or ANTHROPIC_API_KEY / GOOGLE_API_KEY
2. Use the DSL
import asyncio
import nlp2sql
from nlp2sql import ProviderConfig
async def main():
nlp = await nlp2sql.connect(
"postgresql://testuser:testpass@localhost:5432/testdb",
provider=ProviderConfig(provider="openai", api_key="sk-..."),
)
result = await nlp.ask("Show active users by region")
print(result.sql)
print(result.confidence)
print(result.metadata["sql_intent_plan"])
asyncio.run(main())
connect() loads the schema, initializes retrieval indexes, and returns a reusable NLP2SQL client. ask() returns a typed QueryResult.
3. Add Few-Shot Examples
Pass examples directly to connect(). The library handles indexing for you.
nlp = await nlp2sql.connect(
"postgresql://testuser:testpass@localhost:5432/testdb",
provider=ProviderConfig(provider="openai", api_key="sk-..."),
examples=[
{
"question": "Show revenue by source category for the flagship store",
"sql": (
"SELECT d.metric_date, mc.source_category, SUM(d.revenue) AS revenue "
"FROM daily_channel_metrics d "
"JOIN stores s ON d.store_id = s.id "
"JOIN marketing_channels mc ON d.channel_id = mc.id "
"WHERE s.code = 'na_flagship' "
"GROUP BY d.metric_date, mc.source_category"
),
"database_type": "postgres",
}
],
)
4. Add In-Memory Semantic Context
Use semantic context when the same question could map to multiple plausible tables or dimensions.
from nlp2sql import (
DimensionDefinition,
DomainRule,
MetricDefinition,
SemanticContext,
SemanticEntityMapping,
)
semantic_context = SemanticContext(
domain="ecommerce_channel_performance",
canonical_tables=["daily_channel_metrics"],
required_filters=["s.code = 'na_flagship'", "s.region = 'North America'"],
entity_mappings=[
SemanticEntityMapping(
source_term="North America flagship store",
target="store_scope",
resolved_value="na_flagship / North America",
filter_expression="s.code = 'na_flagship' AND s.region = 'North America'",
)
],
metric_definitions=[
MetricDefinition(name="revenue", description="Revenue by day and source category."),
MetricDefinition(name="orders_count", description="Orders by day and source category."),
],
dimension_definitions=[
DimensionDefinition(name="metric_date", description="Daily grain."),
DimensionDefinition(name="source_category", description="Channel grouping."),
],
rules=[
DomainRule(
name="preserve_source_breakdown",
description="Keep source_category when the question asks for a source breakdown.",
required_dimensions=["source_category"],
preferred_tables=["daily_channel_metrics"],
)
],
)
result = await nlp.ask(
"Show daily revenue and order count by source category for the North America flagship store",
semantic_context=semantic_context,
)
5. Validate and Repair
ask() supports execution-aware modes directly.
result = await nlp.ask(
"Show revenue by source category for the flagship store",
validate=True,
repair=True,
)
generate_only: generate SQL onlygenerate_and_validate: execute readonly validation when execution is wiredgenerate_validate_repair: retry on semantic or execution failures when repair hooks are available
6. CLI Parity
The CLI exposes the same concepts:
nlp2sql query \
--database-url postgresql://testuser:testpass@localhost:5432/testdb \
--question "Show daily revenue by source category for the North America flagship store" \
--examples-file examples.json \
--semantic-context-file semantic-context.json \
--validate \
--repair \
--show-semantic-context \
--show-sql-intent-plan \
--show-selected-examples
How It Works
flowchart TD
userCode[UserCodeOrCLI] --> dsl[connectAndAskDSL]
dsl --> analysis[QueryAnalysisService]
analysis --> semantic[SemanticResolutionService]
semantic --> retrieval[SchemaRetrievalAndExampleSelection]
retrieval --> intent[SqlIntentPlanningService]
intent --> prompt[PromptAssemblyAndAdapters]
prompt --> llm[LLMGeneration]
llm --> semval[SemanticValidation]
semval --> exec[OptionalExecutionAndRepair]
exec --> result[QueryResultMetadata]
At runtime the library:
- analyzes the question
- optionally resolves and merges semantic context
- retrieves relevant schema and examples
- builds a structured SQL intent plan
- assembles the prompt
- generates SQL
- optionally validates, executes, and repairs
- returns a
QueryResultwith debug metadata
See Architecture for the full breakdown.
Public Example Domain
This repository ships a local e-commerce integration domain used in tests and docs. It includes:
storesmarketing_channelsusersproductsordersorder_itemsdaily_channel_metrics
The public examples intentionally stay inside that domain to avoid leaking any private warehouse schema.
To start it locally:
cd docker
docker compose up -d postgres
The default URL is:
postgresql://testuser:testpass@localhost:5432/testdb
Provider Comparison
| Provider | Default Model | Context Size | Max Output | Best For |
|---|---|---|---|---|
| OpenAI | gpt-5.6-luna |
1.05M (922K input) | 128K | Fast, low-cost general purpose usage |
| Anthropic | claude-sonnet-5 |
1M | 128K | Larger schemas and long prompts |
| Gemini | gemini-3.8-flash |
1M | 64K | High-volume and very large contexts |
Defaults are pinned snapshot IDs, not floating aliases. Override any of them through ProviderConfig(model=...); for example gpt-5.6-terra is the higher-quality OpenAI option.
Lower-Level API
connect() is the recommended path. Lower-level entry points still exist for advanced wiring:
from nlp2sql import DatabaseType, ProviderConfig, create_and_initialize_service
service = await create_and_initialize_service(
database_url="postgresql://testuser:testpass@localhost:5432/testdb",
provider_config=ProviderConfig(provider="openai", api_key="sk-..."),
database_type=DatabaseType.POSTGRES,
)
result = await service.generate_sql(
"Count active users by region",
database_type=DatabaseType.POSTGRES,
)
print(result["sql"])
Development
git clone https://github.com/luiscarbonel1991/nlp2sql.git
cd nlp2sql
uv sync
# Start the local public e-commerce database
cd docker && docker compose up -d postgres
# Integration tests without llm
cd ..
uv run pytest -m "integration and not llm"
# Optional llm integration tests
uv run pytest -m "integration and llm"
MCP Server
nlp2sql includes a Model Context Protocol server for assistant integration.
{
"mcpServers": {
"nlp2sql": {
"command": "python",
"args": ["/path/to/nlp2sql/mcp_server/server.py"],
"env": {
"OPENAI_API_KEY": "${OPENAI_API_KEY}",
"NLP2SQL_DEFAULT_DB_URL": "postgresql://testuser:testpass@localhost:5432/testdb"
}
}
}
}
See mcp_server/README.md for details.
Contributing
See CONTRIBUTING.md.
License
MIT License. See LICENSE.
nlp2sql MCP questions
Which LLM providers are supported?
The library has built-in support for OpenAI, Anthropic, and Gemini, but you can also pass your own AIProviderPort.
What databases can I connect to?
PostgreSQL and Amazon Redshift are built-in, and you can register additional databases using a SchemaRepositoryPort implementation.