NLSQL MCP Server (Node.js)

A production-ready Node.js package that provides an MCP (Model Context Protocol) server for converting natural language questions into SQL queries using AI-powered multi-agent systems.

Quick Start

# Install globally
npm install -g nlsql-mcp-server

# Start the server
nlsql-mcp-server start

# Or run directly with npx
npx nlsql-mcp-server start

Features

AI-Powered: Converts natural language to SQL using OpenAI and CrewAI
Multi-Database: Supports SQLite, PostgreSQL, and MySQL
Smart Analysis: AI-powered database schema analysis
Easy Installation: One-command setup with automatic Python dependency management
MCP Protocol: Full JSON-RPC implementation compatible with Claude Desktop and other MCP clients
Safe Execution: Query validation and configurable limits
Sample Data: Built-in NBA database for testing
Production Ready: Comprehensive error handling and logging

Prerequisites

Node.js 14+: JavaScript runtime
Python 3.8+: For the underlying MCP server
OpenAI API Key: For natural language processing

Installation

Global Installation (Recommended)

npm install -g nlsql-mcp-server

Local Installation

npm install nlsql-mcp-server

The package will automatically:

Detect your Python installation
Install required Python dependencies
Set up the NLSQL MCP server
Verify the installation

Configuration

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

Claude Desktop Setup (Step-by-Step)

Step 1: Install the Package

npm install -g nlsql-mcp-server

Step 2: Get Your OpenAI API Key

Go to OpenAI API Keys
Create a new API key
Copy the key (starts with sk-)

Step 3: Find Your Claude Desktop Config File

On Windows:

Press Windows + R
Type %APPDATA%\Claude
Look for claude_desktop_config.json

On Mac:

Open Finder
Press Cmd + Shift + G
Type ~/Library/Application Support/Claude
Look for claude_desktop_config.json

On Linux:

Open file manager
Go to ~/.config/Claude
Look for claude_desktop_config.json

Step 4: Edit the Config File

If the file exists: Open it and add the nlsql configuration to the existing mcpServers section.

If the file doesn't exist: Create a new file called claude_desktop_config.json with this content:

{
  "mcpServers": {
    "nlsql": {
      "command": "npx",
      "args": ["nlsql-mcp-server", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-actual-api-key-here"
      }
    }
  }
}

Important: Replace sk-your-actual-api-key-here with your real OpenAI API key!

Step 5: Restart Claude Desktop

Completely close Claude Desktop
Open Claude Desktop again
The nlsql server should now be available

Step 6: Test It Works

In Claude Desktop, try asking:

"Connect to the sample database and show me what tables are available"

If it works, you'll see Claude connect to the NBA sample database!

Usage

Command Line Interface

# Start the MCP server
nlsql-mcp-server start

# Start with debug mode
nlsql-mcp-server start --debug

# Test the installation
nlsql-mcp-server test

# Install/reinstall Python dependencies
nlsql-mcp-server install-deps

# Generate Claude Desktop config
nlsql-mcp-server config

# Show help
nlsql-mcp-server --help

Programmatic Usage

const NLSQLMCPServer = require('nlsql-mcp-server');

const server = new NLSQLMCPServer({
    debug: true,
    pythonExecutable: 'python3',
    env: {
        OPENAI_API_KEY: 'your_key_here'
    }
});

await server.start();

Available Tools

When running, the server provides these MCP tools:

Tool	Description
`connect_database`	Connect to SQLite, PostgreSQL, or MySQL
`connect_sample_database`	Connect to built-in NBA sample database
`natural_language_to_sql`	Convert questions to SQL using AI
`execute_sql_query`	Execute SQL queries safely
`analyze_schema`	AI-powered database schema analysis
`get_database_info`	Get table and column information
`validate_sql_query`	Validate SQL syntax
`get_table_sample`	Get sample data from tables
`get_connection_status`	Check database connection status
`disconnect_database`	Disconnect from database

Examples

Claude Desktop Usage

After setting up Claude Desktop integration, you can use natural language to interact with your databases:

Connect to my sample database and show me the schema

Convert this to SQL: "How many teams are in the NBA?"

Show me sample data from the team table

Analyze my database structure and suggest useful queries

Sample Database

Test with the built-in NBA database (30 teams, 15 tables with players, games, stats):

Use the connect_sample_database tool

Then ask questions like:

"How many teams are in the NBA?" → Returns: 30 teams
"Show me sample data from the team table"
"List teams from California"
"Validate this SQL: SELECT COUNT(*) FROM team"

Testing

# Test the Node.js wrapper
npm test

# Test the underlying Python server
nlsql-mcp-server test

# Test with sample database
nlsql-mcp-server start --debug
# Then use with Claude Desktop

Troubleshooting

Common Issues

"Python not found"

# Install Python 3.8+
# On Ubuntu/Debian:
sudo apt update && sudo apt install python3 python3-pip

# On macOS:
brew install python3

# On Windows:
# Download from python.org

"Failed to install Python dependencies"

# Manual installation
nlsql-mcp-server install-deps

# Or install manually
pip3 install mcp crewai sqlalchemy pandas openai python-dotenv psycopg2-binary pymysql cryptography

"OpenAI API key not found"

# Set environment variable
export OPENAI_API_KEY="your_key_here"

# Or use .env file
echo "OPENAI_API_KEY=your_key_here" > .env

"Server won't start"

# Debug mode for detailed logs
nlsql-mcp-server start --debug

# Test installation
nlsql-mcp-server test

Debug Mode

Run with debug mode for detailed logging:

nlsql-mcp-server start --debug

Log Files

Logs are written to:

Linux/macOS: ~/.config/nlsql-mcp-server/logs/
Windows: %APPDATA%\nlsql-mcp-server\logs\

Integration Examples

VS Code with Continue.dev

Add to your Continue.dev configuration:

{
  "mcpServers": {
    "nlsql": {
      "command": "npx",
      "args": ["nlsql-mcp-server", "start"]
    }
  }
}

Custom Applications

const { spawn } = require('child_process');

const mcpServer = spawn('npx', ['nlsql-mcp-server', 'start'], {
    stdio: ['pipe', 'pipe', 'pipe'],
    env: {
        ...process.env,
        OPENAI_API_KEY: 'your_key_here'
    }
});

// Handle MCP protocol communication
mcpServer.stdout.on('data', handleMCPMessage);
mcpServer.stdin.write(JSON.stringify(mcpRequest));

Performance

Startup Time: ~2-3 seconds
Database Operations: <1 second (connect, query, validate)
AI Processing: 5-15 seconds (natural language to SQL, schema analysis)
Memory Usage: ~100-200MB
Database Support: SQLite, PostgreSQL, MySQL

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests: npm test
Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Original Python Server: NLSQL MCP Server
Underlying Application: nl2sql
Built with: Model Context Protocol (MCP), CrewAI, OpenAI

Support

Issues: GitHub Issues
Documentation: GitHub Repository
Discussions: GitHub Discussions

Made by Tushar Badhwar