nlsql

This MCP server exposes the nl2sql functionality as a collection of tools that can be accessed by any MCP-compatible client. Through the server, you can connect to various databases (SQLite, PostgreSQL, MySQL), analyze schemas, convert natural language questions into SQL queries, validate and execute SQL, and inspect table data. The server acts as a wrapper around the original nl2sql application, enabling AI-driven SQL generation and safe execution within the MCP framework. Use the provided tools to establish a database connection, perform schema analysis, generate SQL from natural language queries, and then run or validate those queries as needed. Built-in prompts assist with common database tasks, making it straightforward to perform end-to-end data inquiries using natural language.

To use the server, configure an MCP client to point at the nlsql MCP server and provide your OpenAI API key. The client configuration shown in the README demonstrates starting the server process and setting the environment so the server can reach OpenAI, then issuing commands like connect_database, analyze_schema, natural_language_to_sql, and execute_sql_query. With this setup, you can explore the NBA sample database, generate SQL from natural language questions, and safely execute or validate the resulting SQL statements.

Prerequisites:

• Python 3.8+
• OpenAI API key
• The original nl2sql application installed in the same parent directory as the MCP server (required dependency)

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

# Navigate to the same parent directory where nl2sql is located
cd ..  # Now you should be in the directory containing nl2sql/

# Clone this MCP server
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

# Set your OpenAI API key
export OPENAI_API_KEY="your_api_key_here"

# Or create a .env file
echo "OPENAI_API_KEY=your_api_key_here" > .env

Step 4: Verify Directory Structure

Ensure your directory structure looks like this:

parent_directory/
├── nl2sql/                # Original nl2sql application (required dependency)
│   ├── main.py
│   ├── database_manager.py
│   ├── crew_setup.py
│   ├── agents.py
│   ├── tasks.py
│   └── nba.sqlite
└── nlsql-mcp-server/      # This MCP server
    ├── src/
    ├── tests/
    ├── README.md
    └── requirements.txt

Important: The MCP server automatically looks for the nl2sql directory in the parent directory. If you have a different setup, you may need to adjust the path in src/nlsql_mcp_server/nlsql_client.py.

Step 5: Run the Server

Standalone mode (standalone):

# Run the server directly
python -m nlsql_mcp_server.server

# Or using the console script (after pip install)
nlsql-mcp-server

With MCP Client: see the example configuration in the README for the exact JSON block to feed your MCP client.

Tips and caveats:

• Ensure nl2sql is installed and its directory is accessible from the MCP server (parent directory relationship is important).
• Export or provide OPENAI_API_KEY in the environment where the MCP server runs; without it, natural language to SQL generation will fail.
• When testing, consider using the built-in NBA sample database via connect_sample_database for quick validation.
• For performance, you can set skip_schema in natural_language_to_sql to speed up queries after initial schema analysis.
• If you encounter import errors, reinstall dependencies with pip install -r requirements.txt and verify Python version compatibility (3.8+).
• The server exposes many tools (connect_database, analyze_schema, natural_language_to_sql, execute_sql_query, validate_sql_query, etc.). Use the provided examples to craft correct tool invocations and argument structures.