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:
Use the connect_sample_database tool to connect to the NBA sample databaseAsk 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 SQLExplore:
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 analysisSet appropriate
limit
values for large result setsUse
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
existsStructure: 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+)
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
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
- -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 -24MIT 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 -MIT 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 -
- -securityFlicense-qualityA 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