Supports environment variable configuration through .env files for setting API keys and other configuration options.
Enables connection to MySQL databases for schema analysis, query execution, and natural language to SQL conversion.
Includes a built-in NBA sample database for testing and demonstration of natural language to SQL conversion capabilities.
Utilizes OpenAI's language models for converting natural language questions into SQL queries and analyzing database schemas.
Supports connection to PostgreSQL databases for schema analysis, query execution, and converting natural language questions to SQL queries.
Provides tools to connect to SQLite databases, analyze schema structure, execute SQL queries, and convert natural language questions to SQL.
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.
Step 2: Install the MCP Server
Step 3: Environment Setup
Step 4: Verify Directory Structure
Ensure your directory structure looks like this:
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
With MCP Client
Configure your MCP client to use this server. Example configuration:
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 tablelimit
(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 questionskip_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 executelimit
(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:
- Ask natural language questions:
- Execute queries:
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
Performance Optimization
- Use
skip_schema: true
innatural_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/
andnlsql-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+)
- Install all required dependencies:
Debug Mode
Enable debug logging:
Testing
The repository includes comprehensive tests to verify your setup:
See tests/README.md for detailed testing documentation.
Development
Project Structure
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
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
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
- -securityAlicense-qualityThis 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 formatLast updated -12PythonMIT License
- -securityAlicense-qualityA Model Context Protocol (MCP) server that enables AI assistants to interact with MySQL databases by executing SQL queries and checking database connectivity.Last updated -TypeScriptMIT License
- -securityFlicense-qualityA 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 -Python
- -securityAlicense-qualityA Model Context Protocol (MCP) server that provides read-only TDengine database queries for AI assistants, allowing users to execute queries, explore database structures, and investigate data directly from AI-powered tools.Last updated -4PythonMIT License