USQL

usql MCP Server

typescript

2

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jvm-usql-mcp": {
      "command": "npx",
      "args": [
        "usql-mcp"
      ],
      "env": {
        "USQL_SQLITE": "sqlite:///path/to/database.db",
        "USQL_POSTGRES": "postgres://user:password@localhost:5432/mydb",
        "USQL_DEFAULT_CONNECTION": "oracle://user:secret@host:1521/service"
      }
    }
  }
}

You run a versatile MCP server that connects the Model Context Protocol to the usql universal SQL CLI, enabling AI assistants and other MCP clients to query many databases through a single interface. It supports background execution, progress tracking, query safety checks, and intelligent caching for reliable, enterprise-ready data access.

How to use

Use the MCP server with your preferred MCP client to query databases through usql. You can run long queries in the background, monitor progress in real time, and rely on built-in safety checks to prevent destructive operations. You’ll also benefit from SQL workflow prompts and browsable database schemas through MCP resources. Integrate with clients like Claude Desktop, Claude Code, Codex CLI, or GitHub Copilot by configuring the MCP server in their MCP settings.

How to install

Prerequisites: ensure you have Node.js 16 or newer and npm installed, and that usql is installed and available on your PATH.

# Get the MCP server source
git clone https://github.com/jvm/usql-mcp.git
cd usql-mcp

# Install dependencies
npm install

# Build the project (produces dist/)
npm run build

Configuration and usage notes

Configure connections by setting environment variables or by using a config.json file that mirrors the example shown in the configuration section. Connection strings allow you to access PostgreSQL, MySQL, Oracle, SQLite, and other databases supported by usql.

To start the MCP server directly with npx, you can run the following. It starts the MCP server on standard input/output.

npx usql-mcp

Security and best practices

Follow secure defaults to protect credentials and data. Use environment variables or secure credential stores for connections, restrict permissions on configuration files, enable SSL/TLS for remote databases, and configure rate limiting to prevent abuse. Enable query safety features to block destructive or high-risk operations when appropriate.

Performance features and maintenance

Leverage schema caching to reduce metadata query overhead and set a reasonable background threshold for long-running queries. Monitor server statistics via the available MCP tools and keep completed job results retained only as long as needed.

Development and testing

Run development tasks to build, lint, test, and type-check the project. Use the provided npm scripts for a smooth workflow.

Available tools

execute_query

Run an arbitrary SQL statement against a specified connection with optional output formats and timeout settings.

execute_script

Execute a multi-statement SQL script against a specified connection with optional output formats and timeout.

list_databases

List all databases available on a given server connection.

list_tables

List tables in the current database for a given connection.

describe_table

Inspect table metadata for a given table via the MCP tool interface.

get_job_status

Check the status of a background job by its ID, with optional wait period.

cancel_job

Cancel a currently running background job by its ID.

get_server_info

Retrieve server configuration and basic statistics in a read-only manner.