Enables execution of SQL queries and database operations against SQLite databases through the usql CLI, including query execution, table listing, and schema inspection.
USQL MCP Server
usql-mcp bridges the Model Context Protocol with the
usql CLI so assistants and other MCP clients can run queries against any
database usql supports. The server forwards tool requests directly to usql and streams the raw CLI
output back to the caller (JSON by default, CSV on request), keeping behaviour identical to what you would
see on the command line.
Requirements
Node.js 16 or newer
npmusqlinstalled and available onPATH
Quick Launch with npm exec
Once the package is published you will be able to run it directly via:
Until it is published, you can still spin it up straight from the repository using npm’s Git support (the
prepare script compiles the TypeScript automatically):
Both commands download the package, build dist/, and execute the CLI entry point (usql-mcp), which
runs the MCP server on stdio.
Getting Started
The compiled files live in dist/. They are intentionally not committed—run npm run build whenever you
need fresh output.
Configuring Connections
Define connection strings via environment variables (USQL_*) or a config.json file mirroring
config.example.json. Each USQL_<NAME>=... entry becomes a reusable connection whose name is the
lower-cased <name> portion (USQL_ORACLE1 → oracle1). Reserved keys that aren’t treated as
connections are:
USQL_CONFIG_PATHUSQL_QUERY_TIMEOUT_MSUSQL_DEFAULT_CONNECTION
Examples:
You can also supply a full URI directly in tool requests. USQL_QUERY_TIMEOUT_MS controls the default
query timeout; leave it unset (or set defaults.queryTimeout to null) for unlimited execution and
override it when you need a guard. Individual tool calls can pass timeout_ms to override (set to
null for unlimited on that call). Set USQL_DEFAULT_CONNECTION (or defaults.defaultConnection in
config.json) to name the connection that should be used automatically when a tool call omits the
connection_string field.
For Claude Desktop, point the MCP configuration to the compiled entry point:
Tool Catalogue
Tool | Purpose | Notable Inputs |
| Run an arbitrary SQL statement |
,
, optional
(
|
),
|
| Execute a multi-statement script |
,
, optional
,
|
| List databases available on the server |
, optional
,
|
| List tables in the current database |
, optional
,
|
| Inspect table metadata via
|
,
, optional
,
|
Successful calls return the exact stdout produced by usql, paired with the format indicator:
If usql exits with a non-zero code the handler forwards the message through the MCP error shape, keeping
details like the sanitized connection string and original stderr.
Development
npm run dev– TypeScript compile in watch modenpm run build– emit ESM output todist/npm run lint– ESLint/Prettier rulesnpm run test– Jest unit tests (no external services required)npm run type-check– stricttsc --noEmit
Debug logging follows the namespace in DEBUG=usql-mcp:*.
Contributing
See AGENTS.md for contributor guidelines. Open an issue before large changes so we can keep the tooling
lean and aligned with the MCP ecosystem.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI assistants to execute SQL queries against any database supported by the usql CLI tool. Provides seamless database interaction through MCP by forwarding queries directly to usql and returning results in JSON or CSV format.