NLP Database Server

Connect your LLMs to SQL databases safely and intuitively using the Model Context Protocol (MCP). NLP Database acts as a secure, read-only bridge that allows AI agents to explore schemas and query data using natural language.

---

🚀 Key Features

• Read-Only Security: Strict regex validation ensures only SELECT and WITH statements are executed.
• Smart Guardrails: Automatic LIMIT 500 on all queries to prevent system bloat.
• Universal Compatibility: Native support for PostgreSQL, MySQL, SQL Server, and SQLite.
• Agent-Optimized: Designed to provide descriptive errors that help LLMs self-correct.
• Performance: 5-minute schema caching to reduce database overhead.

---

Usage Example

Once the server is connected to your LLM (Claude, Gemini, etc.), the agent gains access to two main tools: get_schema and execute_query.

Typical Workflow

1. Exploration: The user asks a question like: "How many users signed up last month?"
2. Schema Inspection: The LLM automatically calls get_schema to understand your table names and columns.
3. Query Execution: The LLM generates a SQL query and calls execute_query.
4. Natural Response: The LLM receives the data and translates it back to you in plain English or Spanish.

Example Interaction

User:

"List the top 3 products by total sales revenue."

LLM (Internal Thought Process):

1. Call get_schema to find relevant tables (finds products and orders).
2. Generate SQL: SELECT p.name, SUM(o.amount) FROM products p JOIN orders o ON p.id = o.product_id GROUP BY p.name ORDER BY 2 DESC LIMIT 3.
3. Call execute_query with the generated SQL.

LLM Response:

"The top 3 products by revenue are:

1. Enterprise Subscription ($50,200)
2. Professional License ($32,150)
3. Basic Plan ($12,400)"

---

Available Tools

Tool	Parameters	Description
get_schema	(none)	Returns a list of all tables, their columns, and data types.
execute_query	sql_query	Executes a safe SELECT statement and returns the results as JSON.

---

🛠️ 1. Installation & Drivers

Step 1: Clone the Repository

git clone https://github.com/your-repo/nlp-database.git
cd nlp-database

Step 2: Install Dependencies

You can install dependencies directly or use a virtual environment (recommended for isolation).

Option A: Using a Virtual Environment (Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Option B: Direct Installation

pip install -r requirements.txt

Step 3: Install Database Drivers

Install only the driver required for your specific database:

• PostgreSQL: pip install psycopg2-binary
• MySQL: pip install pymysql
• SQL Server: pip install pyodbc
• SQLite: Already included in Python standard library.

---

🔗 2. Connection Strings (DATABASE_URL)

Database	Connection String Format
PostgreSQL	postgresql://user:pass@localhost:5432/dbname
MySQL	mysql+pymysql://user:pass@localhost:3306/dbname
SQL Server	mssql+pyodbc://user:pass@server/db?driver=ODBC+Driver+17+for+SQL+Server
SQLite	sqlite:///C:/absolute/path/to/database.db

---

⚙️ 3. Client Configuration

A. Claude Code (CLI)

claude mcp add nlp-database -- python C:/path/to/nlp_database.py --env DATABASE_URL="your_connection_string"

B. Gemini CLI

Add this to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "nlp-database": {
      "command": "python",
      "args": ["C:/path/to/nlp_database.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

C. Google Antigravity

Locate your mcp_config.json (usually in ~/.gemini/antigravity/):

{
  "mcpServers": {
    "nlp-database": {
      "command": "python",
      "args": ["C:/path/to/nlp_database.py"],
      "env": {
        "DATABASE_URL": "mssql+pyodbc://user:pass@server/db?driver=ODBC+Driver+17+for+SQL+Server"
      }
    }
  }
}

D. OpenCode

Edit %USERPROFILE%\.opencode\opencode.jsonc:

{
  "mcp": {
    "nlp-database": {
      "type": "local",
      "command": "python",
      "args": ["C:/path/to/nlp_database.py"],
      "enabled": true,
      "environment": {
        "DATABASE_URL": "mysql+pymysql://user:pass@localhost/db"
      }
    }
  }
}

E. Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nlp-database": {
      "command": "python",
      "args": ["C:/path/to/nlp_database.py"],
      "env": {
        "DATABASE_URL": "sqlite:///C:/data/prod.db"
      }
    }
  }
}

---

Aquí tienes el apartado diseñado para resaltar la privacidad y la facilidad de uso con modelos locales. Puedes insertarlo justo antes de la sección de Security.

---

Running with Local Models (100% Private)

For maximum privacy, you can pair NLP Database with a local LLM. This ensures that your database schema and query results never leave your machine.

Using Ollama + Claude Desktop / OpenCode

1. Install Ollama: Download it from ollama.com.
2. Pull a Model: Recommended models for SQL generation are llama3.1, codellama, or qwen2.5-coder.

ollama run llama3.1

3. Configure your Client: Point your MCP client to your local Python script as shown in the Client Configuration section.
4. Select Local Model: In your client (like OpenCode or a local-ready editor), select your Ollama endpoint (usually http://localhost:11434) as the provider.

Why go local?

Feature	Local Model	Cloud Model (OpenAI/Anthropic)
Data Privacy	🔒 Total. Data stays on your disk.	🌐 Data sent to 3rd party servers.
Cost	💰 Free. Uses your own GPU/CPU.	💳 Pay-per-token.
Internet	🔌 Not required. Works offline.	🌐 Required.
Latency	⚡ Depends on your hardware.	☁️ Depends on API response time.

---

🔒 Security: Dedicated Read-Only User

Always use a restricted database user. Here is how to create one:

PostgreSQL Example:

CREATE USER nlp_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE my_db TO nlp_readonly;
GRANT USAGE ON SCHEMA public TO nlp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO nlp_readonly;

---

📝 Configuration Options

Environment Variable	Default	Description
DATABASE_URL	Required	SQLAlchemy connection string.
MAX_RESULT_ROWS	500	Max rows returned to the LLM.
QUERY_TIMEOUT	30	Max execution time in seconds.
DB_ECHO_SQL	false	Enable to log raw SQL queries to console.

---

🤝 Contributing

This is an open-source project and I'd love your help to make it better! Whether you are a Python expert, a Data Engineer, or just starting with MCP, your contributions are welcome.

How to help:

• Report bugs or suggest features via Issues.
• Improve documentation.
• Add support for more database engines.
• Submit Pull Requests with your improvements.