NLSQL

You can run the NLSQL MCP Server to expose nl2sql AI-powered natural language to SQL as programmable MCP tools. This lets you connect to databases, analyze schemas, translate questions into SQL, and execute queries safely from any MCP-compatible client.

How to use

Use an MCP client to connect to the server, analyze your database, convert natural language questions into SQL, and run queries. Start by launching the server locally, then configure your client to access the available tools such as connecting to a database, analyzing the schema, translating questions to SQL, and executing or validating SQL queries. You can also inspect sample data and fetch table samples to validate results before running complex queries.

How to install

Prerequisites: You need Python 3.8 or newer and an OpenAI API key. Install the nl2sql application first, then install the MCP server.

# Step 1: Install the NLSQL Application (Required)
# Clone the original nl2sql application
git clone https://github.com/tushar-badhwar/nl2sql.git
cd nl2sql

# Install dependencies
pip install -r requirements.txt

# Test the installation
streamlit run main.py

# Step 2: Install the MCP Server
cd ..  # Move to the parent directory containing nl2sql/
git clone https://github.com/tushar-badhwar/nlsql-mcp-server.git
cd nlsql-mcp-server

# Install MCP server dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

# Step 3: Environment Setup
export OPENAI_API_KEY="your_api_key_here"
# Or use a .env file
echo "OPENAI_API_KEY=your_api_key_here" > .env

# Step 4: Verify Directory Structure
# Ensure nl2sql/ and nlsql-mcp-server/ exist in the same parent directory

Additional setup notes

The MCP server looks for the nl2sql directory in the parent directory. If your setup differs, adjust the path in the client interface accordingly.

Server start options

Run the MCP server in standalone mode or via an MCP client. The following commands start the server locally in stdio mode.

# Standalone start (stdio)
python -m nlsql_mcp_server.server

# Alternative executable script after installation
nlsql-mcp-server

Configure an MCP client

Configure your MCP client to point at the local server, using the stdio command shown above. The client should invoke the server process so you can send tool requests (connect_database, analyze_schema, natural_language_to_sql, etc.) and receive results.

Notes on security and usage

Protect your OpenAI API key and only expose the MCP server to trusted clients. Use the built-in prompts and safeguards to validate SQL syntax before execution and to apply query limits for safety.

Troubleshooting tips

If the server cannot start, confirm you have the nl2sql application installed in the expected location, verify Python and pip versions, and ensure OPENAI_API_KEY is set. Check environment setup and ensure dependencies install without errors.

Available tools

connect_database

Connect to a database (sqlite, postgresql, mysql) by providing the appropriate connection details.

connect_sample_database

Connect to the built-in NBA sample database for testing.

analyze_schema

Analyze the database schema and structure using AI to reveal tables, columns, and relationships.

get_database_info

Retrieve detailed information about the connected database, including tables, columns, and relationships.

get_table_sample

Fetch sample rows from a specified table to preview data.

natural_language_to_sql

Convert a natural language question into an SQL query using AI.

execute_sql_query

Execute a SQL query on the connected database with optional result limits.

validate_sql_query

Validate the syntax and structure of a given SQL query.

get_connection_status

Check the current database connection status.

disconnect_database

Disconnect from the currently connected database.

analyze_database

Comprehensive database analysis workflow using built-in prompts.

generate_sql_query

Workflow to translate natural language to SQL with schema considerations.

troubleshoot_sql

Workflow to troubleshoot SQL queries and performance issues.