nlp2sqlBLOCK
Enterprise-ready Natural Language to SQL converter with multi-provider AI support (OpenAI, Anthropic, Gemini). Built for production scale databases (1000+ tables) with Clean Architecture.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
DSL-first natural language to SQL for PostgreSQL and Redshift
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
- 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
- Database support: PostgreSQL and Amazon Redshift
- Async by default: built for services, APIs, notebooks, and workers
Documentation
a44865a3adceOBSERVED · 2026-10-10Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add nlp2sql --env ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} --env GOOGLE_API_KEY=${GOOGLE_API_KEY} --env NLP2SQL_TEST_POSTGRES_PASS=${NLP2SQL_TEST_POSTGRES_PASS} --env OPENAI_API_KEY=${OPENAI_API_KEY} -- uvx nlp2sql{
"mcpServers": {
"nlp2sql": {
"command": "uvx",
"args": [
"nlp2sql"
],
"env": {
"ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
"GOOGLE_API_KEY": "${GOOGLE_API_KEY}",
"NLP2SQL_TEST_POSTGRES_PASS": "${NLP2SQL_TEST_POSTGRES_PASS}",
"OPENAI_API_KEY": "${OPENAI_API_KEY}"
}
}
}
}Exposed tools (5)
4 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
ask_database | read | Ask a question about your data in natural language. |
explain_sql | read | Explain what a SQL query does in plain English. |
explore_schema | read | Explore the database schema to understand available tables and columns. |
list_databases | read | List all configured database connections. |
run_sql | write | Execute a SQL query and return results. |
Trust audit
BLOCKgrade D · trust 68/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (2 observation(s))
- Network
- declared (1 observation(s))
- Shell
- declared (5 observation(s))
- Dependencies
- pinned
- Secrets in source
- found
Findings (18)
cache_data = pickle.load(f)
cache_data = pickle.load(f)
cache_data = pickle.load(f)
cache_data = pickle.load(f)
cache_data = pickle.load(f)
- Simple: postgresql://testuser:testpass@localhost:5432/testdb
- Enterprise: postgresql://demo:demo123@localhost:5433/enterprise
uv run nlp2sql query --database-url "postgresql://testuser:testpass@localhost:5432/testdb" --question "How many users?"
# Simple DB: postgresql://testuser:testpass@localhost:5432/testdb
# Enterprise DB: postgresql://demo:demo123@localhost:5433/enterprise
.mcp.json.example
self.namespace = hashlib.md5(index_key.encode(), usedforsecurity=False).hexdigest()
return hashlib.md5(content.encode(), usedforsecurity=False).hexdigest()
url_hash = hashlib.md5(self.connection_string.encode()).hexdigest()[:12]
url_hash = hashlib.md5(self.connection_string.encode()).hexdigest()[:12]
db_hash = hashlib.md5(index_key.encode()).hexdigest()
2. **Use read-only database credentials** when possible
cat > .env << EOF
Gates applied: no_behavioural_pass.
a44865a3adcefull audit observations/trust-audit/mcp-server/luiscarbonel1991__nlp2sql.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-10 | a44865a3adce | BLOCK | D | 68 | first audit |
Questions
What is the nlp2sql MCP server?
Enterprise-ready Natural Language to SQL converter with multi-provider AI support (OpenAI, Anthropic, Gemini). Built for production scale databases (1000+ tables) with Clean Architecture.
What tools does nlp2sql expose?
5 in total: 4 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is nlp2sql safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (68/100) and found 7 critical or high issues in the source. Each one is listed on this page with the file and line it is on.
What credentials does nlp2sql need?
It reads ANTHROPIC_API_KEY, GOOGLE_API_KEY, NLP2SQL_TEST_POSTGRES_PASS and OPENAI_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How current is this page?
The grade is for one exact copy of the source (a44865a3adce), read on 2026-10-10. The repository is watched and re-audited when it changes.