NLSQL MCP Server (Node.js)

A Node.js package that runs an MCP (Model Context Protocol) server for talking to your databases in natural language. Works with SQLite, PostgreSQL, and MySQL, and plugs into any MCP client (Claude Desktop, etc.).

Quick start

# 1. Install. Auto-builds an isolated Python environment (~3 min, one time).
npm install -g nlsql-mcp-server

# 2. Verify it's ready.
nlsql-mcp-server test

Then add this to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux):

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

Fully restart Claude Desktop, then ask:

Connect to the sample database and tell me how many teams are in the NBA.

That's it — no OpenAI key required. Claude reads the schema with the key-free tools and writes the SQL itself. (First call only, this triggers a one-off ~52 MB sample-DB download.)

Requirements

• Node.js 14+
• Python 3.10, 3.11, 3.12, or 3.13 — not 3.14. The underlying CrewAI engine doesn't support 3.14 yet. The installer auto-detects a compatible interpreter; if none is found it prints exact install instructions for your OS.
• OpenAI API key — optional, only for the server-side AI tools (natural_language_to_sql, analyze_schema). With Claude Desktop you don't need one — Claude handles the natural-language part itself.

Install — what happens

npm install -g nlsql-mcp-server runs a postinstall script that:

1. Probes for a compatible Python (python3.13 → 3.12 → 3.11 → 3.10).
2. Builds a dedicated virtualenv inside the package and installs the slim runtime dependency set. Isolated from your system Python; not affected by PEP 668.
3. Prints Setup complete.

If no compatible Python is found, the install still finishes but prints recovery instructions:

macOS:   brew install [email protected]
Ubuntu:  sudo apt install python3.13 python3.13-venv
Windows: winget install Python.Python.3.13

Install one of those, then run:

nlsql-mcp-server install-deps   # (re)builds the virtualenv

Use with Claude Desktop

Important: run npm install -g nlsql-mcp-server and nlsql-mcp-server test before adding the config below. The one-time Python environment build takes a few minutes and can't finish inside an MCP client's startup handshake — if you wire it in first, the server exits immediately telling you (in the Claude Desktop logs) to run nlsql-mcp-server install-deps once in a terminal.

The minimal config is in Quick start — no key needed. To enable the optional server-side AI tools (CrewAI/OpenAI does the NL→SQL inside the server instead of letting Claude do it), add an OPENAI_API_KEY:

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

What you can ask Claude

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

How many teams from California are in the NBA?

Connect to my Postgres at postgresql://user:pass@host:5432/db and tell me
about the schema.

Claude reads the schema with the key-free tools, writes the SQL, runs it, and answers — no OpenAI account in the loop unless you added a key.

Available tools

| Tool | Needs OpenAI key? | Description | |------|:---:|-------------| | connect_database | – | Connect to SQLite, PostgreSQL, or MySQL | | connect_sample_database | – | Connect to the NBA sample DB (downloaded on first use) | | get_database_info | – | Tables, columns, relationships | | get_table_sample | – | Sample rows from a table | | validate_sql_query | – | Validate SQL syntax | | execute_sql_query | – | Execute SQL safely | | get_connection_status | – | Current connection status | | disconnect_database | – | Disconnect | | natural_language_to_sql | ✅ | Convert a question to SQL using AI | | analyze_schema | ✅ | AI-powered schema analysis |

The two ✅ tools are advertised only when OPENAI_API_KEY is set. With no key, only the 8 key-free tools are exposed — a capable MCP client like Claude Desktop handles natural-language→SQL itself using those primitives.

CLI

nlsql-mcp-server start            # start the MCP server (stdio)
nlsql-mcp-server start --debug    # start with verbose logging
nlsql-mcp-server test             # check venv + deps + key
nlsql-mcp-server install-deps     # (re)build the Python virtualenv
nlsql-mcp-server config           # print a Claude Desktop config snippet
nlsql-mcp-server --help

Troubleshooting

No CrewAI-compatible Python found (need 3.10–3.13) Your default Python is 3.14 (or none in range). Install a compatible one (brew install [email protected], apt install python3.13 python3.13-venv, or winget install Python.Python.3.13), then run nlsql-mcp-server install-deps.

Claude Desktop shows the server failing immediately Check the MCP client logs. If it says the Python environment isn't built, run nlsql-mcp-server install-deps once in a terminal, wait for it to finish, then fully restart Claude Desktop. This happens when the server was wired in before the one-time environment build completed.

natural_language_to_sql returns a credentials error OPENAI_API_KEY isn't set in the environment the server runs in. For Claude Desktop, put it in the env block of the config. The 8 key-free tools work without it.

Reinstall the Python environment from scratch

nlsql-mcp-server install-deps

Deletes and rebuilds the package virtualenv.

How it works

MCP client (Claude Desktop)
        │  JSON-RPC over stdio
        ▼
Node wrapper (index.js)  ──spawns──►  Python MCP server (package virtualenv)
                                          │
                                          ▼
                                   nl2sql + CrewAI agents
                                   SQLite / PostgreSQL / MySQL

The Node layer manages the isolated Python virtualenv and process; the Python layer runs the MCP protocol and the SQL/AI logic.

Testing

npm test                  # Node wrapper unit tests
nlsql-mcp-server test     # installation / environment checks

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 — see LICENSE.

Credits

• Original Python server: NLSQL MCP Server
• Underlying application: nl2sql
• Built with: Model Context Protocol, CrewAI, OpenAI

Support

• Issues: GitHub Issues
• Repository: GitHub

Made by Tushar Badhwar