NLSQL MCP Server

An MCP (Model Context Protocol) server that exposes the functionality of the nl2sql Natural Language to SQL application as MCP tools. This allows any MCP-compatible client to convert natural language questions into SQL queries using AI.

Features

Database Connection: Connect to SQLite, PostgreSQL, and MySQL databases
Schema Analysis: Automatically analyze database structure and relationships
Natural Language to SQL: Convert plain English questions to SQL queries using AI
Query Execution: Execute SQL queries safely with configurable limits
Query Validation: Validate SQL syntax before execution
Sample Data: Access sample data from database tables
Built-in Prompts: Pre-configured prompts for common database tasks

Prerequisites

NLSQL Application: This MCP server is a wrapper around the nl2sql application. You must install nl2sql first.
OpenAI API Key: Required for natural language to SQL conversion
Python 3.8+: Compatible with Python 3.8 and above

Installation

Step 1: Install the NLSQL Application (Required)

This MCP server requires the original nl2sql application to be installed first.

# 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.

Running the Server

Standalone Mode

# Run the server directly
python -m nlsql_mcp_server.server

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

With MCP Client

Configure your MCP client to use this server. Example configuration:

{
  "mcpServers": {
    "nlsql": {
      "command": "python",
      "args": ["-m", "nlsql_mcp_server.server"],
      "cwd": "/path/to/nlsql-mcp-server",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Database Connection Tools

`connect_database`

Connect to SQLite, PostgreSQL, or MySQL database.

Parameters:

db_type (required): "sqlite", "postgresql", or "mysql"
file_path: Path to SQLite file (SQLite only)
host, port, database, username, password: Connection details (PostgreSQL/MySQL)

`connect_sample_database`

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

Schema Analysis Tools

`analyze_schema`

Analyze database schema and structure using AI.

Parameters:

force_refresh (optional): Force refresh of schema cache

`get_database_info`

Get detailed database information including tables, columns, and relationships.

`get_table_sample`

Get sample data from a specific table.

Parameters:

table_name (required): Name of the table
limit (optional): Number of rows to return (default: 5)

Natural Language to SQL Tools

`natural_language_to_sql`

Convert natural language question to SQL query using AI.

Parameters:

question (required): Natural language question
skip_schema (optional): Skip schema analysis for faster processing

SQL Execution Tools

`execute_sql_query`

Execute SQL query on connected database.

Parameters:

sql_query (required): SQL query to execute
limit (optional): Maximum rows to return (default: 100)

`validate_sql_query`

Validate SQL query syntax and structure.

Parameters:

sql_query (required): SQL query to validate

Utility Tools

`get_connection_status`

Get current database connection status.

`disconnect_database`

Disconnect from current database.

Available Prompts

`analyze_database`

Comprehensive database analysis workflow.

`generate_sql_query`

Natural language to SQL generation workflow.

`troubleshoot_sql`

SQL query troubleshooting workflow.

Usage Examples

Using with Claude Desktop

Configure Claude Desktop to use this MCP server
Connect to a database:
Use the connect_sample_database tool to connect to the NBA sample database
Ask natural language questions:
Use the natural_language_to_sql tool with the question "How many teams are in the NBA?"
Execute queries:
Use the execute_sql_query tool to run the generated SQL

Example Workflow

Connect: connect_sample_database
Analyze: analyze_schema
Query: natural_language_to_sql with question "List all teams from California"
Execute: execute_sql_query with the generated SQL
Explore: get_table_sample for additional data exploration

Advanced Usage

Custom Database Connection

{
  "tool": "connect_database",
  "arguments": {
    "db_type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "database": "mydb",
    "username": "user",
    "password": "password"
  }
}

Performance Optimization

Use skip_schema: true in natural_language_to_sql for faster queries after initial schema analysis
Set appropriate limit values for large result sets
Use get_table_sample to explore data before writing complex queries

Troubleshooting

Common Issues

"Could not find the nl2sql application" or "nlsql modules not found"
- Solution: Install the original nl2sql application first
- Command: git clone https://github.com/tushar-badhwar/nl2sql.git
- Verify: Check that nl2sql/database_manager.py exists
- Structure: Ensure both nl2sql/ and nlsql-mcp-server/ are in the same parent directory
"OpenAI API key not found"
- Set the OPENAI_API_KEY environment variable
- Verify the API key is valid
Database connection failures
- Check database credentials and connectivity
- Ensure database server is running
- Verify firewall settings for remote databases
Import errors
- Install all required dependencies: pip install -r requirements.txt
- Check Python version compatibility (3.8+)

Debug Mode

Enable debug logging:

export PYTHONPATH=/path/to/nlsql-mcp-server/src
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from nlsql_mcp_server.server import main
import asyncio
asyncio.run(main())
"

Testing

The repository includes comprehensive tests to verify your setup:

# Basic functionality test (no API key required)
python3 tests/test_basic.py

# Full setup validation
python3 tests/test_setup.py

# AI functionality test (requires OpenAI API key)
python3 tests/test_with_api.py

See tests/README.md for detailed testing documentation.

Development

Project Structure

src/
├── nlsql_mcp_server/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── tools.py           # MCP tool definitions
│   └── nlsql_client.py    # Interface to nlsql app
├── pyproject.toml
└── requirements.txt

Adding New Tools

Define the tool in tools.py
Add handler method in NLSQLTools.call_tool()
Implement the functionality in nlsql_client.py
Update documentation

Testing

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy src/

# Format code
black src/
isort src/

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Support

For issues and questions:

Create an issue in the GitHub repository
Check the troubleshooting section above
Review the nlsql application documentation

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

An MCP (Model Context Protocol) server that exposes natural language to SQL functionality, allowing any MCP-compatible client to convert plain English questions into SQL queries for database interaction using AI.

Related MCP Servers

MCP Databricks Server
RafaelCartenet
-
security
A
license
-
quality
This is a Model Context Protocol (MCP) server for executing SQL queries against Databricks using the Statement Execution API. It enables AI assistants to directly query Databricks data warehouses, analyze database schemas, and retrieve query results in a structured format
Last updated -
19
MIT License
MCP MySQL App
zalab-inc
-
security
A
license
-
quality
A Model Context Protocol (MCP) server that enables AI assistants to interact with MySQL databases by executing SQL queries and checking database connectivity.
Last updated -
MIT License
MCP SQL Server
dennismartis
-
security
F
license
-
quality
A FastMCP server that provides natural language interaction with MS SQL databases, enabling users to query data, list tables, describe structures, and execute database operations through a conversational AI interface.
Last updated -
Natural Language MySQL Query System
floatDreamWithSong
-
security
F
license
-
quality
A Model Context Protocol (MCP) server that converts natural language queries into SQL statements, allowing users to query MySQL databases using conversational language instead of writing SQL code.
Last updated -
3

View all related MCP servers

Appeared in Searches

Natural Language to SQL Conversion and Executing MySQL Queries to Retrieve Data

NLSQL MCP Server

Features

Prerequisites

Installation

Step 1: Install the NLSQL Application (Required)

Step 2: Install the MCP Server

Step 3: Environment Setup

Step 4: Verify Directory Structure

Running the Server

Standalone Mode

With MCP Client

Available Tools

Database Connection Tools

connect_database

connect_sample_database

Schema Analysis Tools

analyze_schema

get_database_info

get_table_sample

Natural Language to SQL Tools

natural_language_to_sql

SQL Execution Tools

execute_sql_query

validate_sql_query

Utility Tools

get_connection_status

disconnect_database

Available Prompts

analyze_database

generate_sql_query

troubleshoot_sql

Usage Examples

Using with Claude Desktop

Example Workflow

Advanced Usage

Custom Database Connection

Performance Optimization

Troubleshooting

Common Issues

Debug Mode

Testing

Development

Project Structure

Adding New Tools

Testing

License

Contributing

Support

Related MCP Servers

MCP Databricks Server

MCP MySQL App

MCP SQL Server

Natural Language MySQL Query System

Appeared in Searches

New MCP Servers

MCP directory API

`connect_database`

`connect_sample_database`

`analyze_schema`

`get_database_info`

`get_table_sample`

`natural_language_to_sql`

`execute_sql_query`

`validate_sql_query`

`get_connection_status`

`disconnect_database`

`analyze_database`

`generate_sql_query`

`troubleshoot_sql`