Skip to main content
Glama

NLSQL MCP Server

by tushar-badhwar
npmGitHub
Python
MIT License
1
1
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

NLSQL MCP Server (Node.js)

npm version npm downloads License: MIT

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:

  1. Detect your Python installation

  2. Install required Python dependencies

  3. Set up the NLSQL MCP server

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

  1. Go to OpenAI API Keys

  2. Create a new API key

  3. Copy the key (starts with sk-)

Step 3: Find Your Claude Desktop Config File

On Windows:

  1. Press Windows + R

  2. Type %APPDATA%\Claude

  3. Look for claude_desktop_config.json

On Mac:

  1. Open Finder

  2. Press Cmd + Shift + G

  3. Type ~/Library/Application Support/Claude

  4. Look for claude_desktop_config.json

On Linux:

  1. Open file manager

  2. Go to ~/.config/Claude

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

  1. Completely close Claude Desktop

  2. Open Claude Desktop again

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

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run tests: npm test

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Support

Made by

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

A Node.js package that provides a Model Context Protocol server for converting natural language questions into SQL queries using AI-powered multi-agent systems.

  1. Quick Start
    1. Features
      1. Prerequisites
        1. Installation
          1. Global Installation (Recommended)
          2. Local Installation
        2. Configuration
          1. Environment Setup
          2. Claude Desktop Setup (Step-by-Step)
        3. Usage
          1. Command Line Interface
          2. Programmatic Usage
        4. Available Tools
          1. Examples
            1. Claude Desktop Usage
            2. Sample Database
          2. Testing
            1. Troubleshooting
              1. Common Issues
              2. Debug Mode
              3. Log Files
            2. Integration Examples
              1. VS Code with Continue.dev
              2. Custom Applications
            3. Performance
              1. Contributing
                1. License
                  1. Credits
                    1. Support

                      Related MCP Servers

                      • SQLite MCP Server

                        santos-404
                        -
                        security
                        A
                        license
                        -
                        quality
                        A Model Context Protocol server implementation that enables AI assistants to execute SQL queries and interact with SQLite databases through a structured interface.
                        Last updated -
                        7
                        MIT License

                      • MySQL MCP Server

                        caicongyang
                        -
                        security
                        F
                        license
                        -
                        quality
                        A Model Context Protocol server that enables AI models to interact with MySQL databases through natural language, supporting SQL queries, table creation, and schema exploration.
                        Last updated -
                        3
                        • Linux
                        • Apple

                      • MySQL MCP Server

                        michael7736
                        A
                        security
                        F
                        license
                        A
                        quality
                        A Model Context Protocol server that allows AI agents to execute SQL queries against a MySQL database, supporting operations like reading data, creating tables, inserting, updating, and deleting records.
                        Last updated -
                        6
                        220
                        7
                        • Apple

                      • BlazeSQL MCP Server

                        arjshiv
                        A
                        security
                        F
                        license
                        A
                        quality
                        A Model Context Protocol server that enables AI clients to interact with BlazeSQL's Natural Language Query API, allowing natural language queries against SQL databases.
                        Last updated -
                        1
                        • Linux
                        • Apple

                      View all related MCP servers

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/tushar-badhwar/nlsql-mcp-server-npm'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server