daviziks/usql-mcp-server

usql-mcp-server

This project is not related or affiliated with official USQL CLI.

An MCP (Model Context Protocol) server that executes SQL queries using the usql universal SQL client.

Features

• Execute SELECT queries against various databases through usql
• JSON output format for structured data
• Support for multiple database connection strings (anything that is compatible with USQL)
• Automatic usql binary download (optional and not recommended)

TODO(s)

• Add tests for when users opt-in for dowloading the binary
• Publish to npm registry and make it be usable just only passing bunx usql-mcp-server and the enviroment variables
• Improve docs
• Add contrib section on README.md

Setup

To install dependencies:

bun install

To tests

bun test

Configuration

Set database connection strings as environment variables:

export DB_CS_1="postgres://user:pass@host:port/db"
export DB_CS_2="mysql://user:pass@host:port/db"
export DB_CS_3="/home/davio/northwind.db"  # SQLite file path
# Add more as needed: DB_CS_4, DB_CS_5, etc.

Database connection strings can be:

• Standard database URLs (postgres://, mysql://, etc.)
• Absolute file paths for SQLite databases (e.g., /home/davio/northwind.db)

Binary Setup

Option 1: Use system usql

Install usql on your system and ensure it's in PATH.

Option 2: Auto-download (unsafe)

Set UNSAFE_USQL_BINARY=true to automatically download the usql binary.

export UNSAFE_USQL_BINARY=true

Usage

Run the MCP server:

bun run index.ts

The server provides a run-query tool that:

• Takes a SQL query (SELECT only)
• Takes a connection string number (1, 2, etc.)
• Executes: usql <connection_string> -c "<query>" -J
• Returns JSON formatted results

Security

• Only SELECT queries are allowed
• No DDL/DML operations (INSERT, UPDATE, DELETE, DROP, etc.)

This project was created using bun init in bun v1.2.21. Bun is a fast all-in-one JavaScript runtime.