OmniSQL MCP

Name: OmniSQL MCP
Author: Sarthak Jain

SQL access to seven database engines from a JSON config or your saved DBeaver connections

By Sarthak Jain (individual) TypeScript Local · stdio Databases

GitHub npm Website

43 popularity score ★ 90 ↓ 258/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add omnisql -- npx -y omnisql-mcp@latest

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "omnisql": {
      "command": "npx",
      "args": [
        "-y",
        "omnisql-mcp@latest"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "omnisql": {
      "command": "npx",
      "args": [
        "-y",
        "omnisql-mcp@latest"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "omnisql": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "omnisql-mcp@latest"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.omnisql]
command = "npx"
args = ["-y", "omnisql-mcp@latest"]

Gemini CLITerminal

gemini mcp add --scope user omnisql npx -- -y omnisql-mcp@latest

Settings 12

`OMNISQL_CONFIG_FILE`	Optional: Path to a JSON file listing database instances and their settings; turns workspace discovery off unless OMNISQL_DISCOVER_WORKSPACE=true.
`OMNISQL_WORKSPACE`	Optional: Path to the DB client workspace; the OS's usual location when unset.
`OMNISQL_DISCOVER_WORKSPACE`	Optional: Whether to read saved workspace connections. Default `false with a config file, true otherwise`.
`OMNISQL_PROJECT`	Optional: Read only this workspace project folder; all projects when unset.
`OMNISQL_POLICY_FILE`	Optional: Path to extra schema, table, function and database access rules.
`OMNISQL_READ_ONLY`	Optional: Set to false to show the write and transaction tools. Default `true`.
`OMNISQL_ALLOWED_CONNECTIONS`	Optional: Comma-separated connection IDs or names to expose; all when unset.
`OMNISQL_DISABLED_TOOLS`	Optional: Comma-separated tool names to turn off.
`OMNISQL_DUCKDB_CLI`	Optional: Path to the DuckDB executable when it is not on PATH. Default `duckdb`. For DuckDB connections.
`OMNISQL_TIMEOUT`	Optional: Query timeout in milliseconds. Default `30000`.
`OMNISQL_POOL_MAX`	Optional: Maximum connections per pool, 1 to 32. Default `4`.
`OMNISQL_UPDATE_NOTIFIER`	Optional: Set to false to stop the daily npm version check. Default `true`.

What it does

OmniSQL MCP is a local stdio server that gives an assistant SQL access to databases you describe in a JSON config file (OMNISQL_CONFIG_FILE) or have already saved in a DBeaver-compatible client. From a workspace it reads both the older XML layout and the newer JSON one and decrypts the passwords kept in credentials-config.json. Connections reached through an SSH tunnel or AWS RDS IAM sign-in are handled too.

PostgreSQL, MySQL/MariaDB, SQL Server and Oracle go through Node drivers, and ClickHouse is spoken to over HTTP. SQLite needs the sqlite3 program and DuckDB its own CLI. Postgres-compatible engines such as CockroachDB, Redshift, Supabase or Neon use the PostgreSQL driver. Any other engine now gets an error, since the old fallback to an outside client CLI is gone. The code still reads OMNISQL_CLI_PATH, but the workspace client no longer uses the value (dist/server.js, dist/workspace-client.js).

It starts read-only. The eight write and transaction tools are left out of the tool list until OMNISQL_READ_ONLY=false, so 18 of its 26 tools show by default. Big results are kept behind short-lived handles that you page through with read_result, read_result_cell and read_export. Notes from append_insight are written to insights.json under ~/.cache/omnisql-mcp/notes, keeping the last 1,000 and at most 1 MiB (dist/runtime/notes.js).

What it needs

Runtime	Node.js 22.15+Bun 1.4.3+
Runs on	macOS, Windows, Linux
Also	A DBeaver-compatible workspace or a JSON connections file sqlite3 CLI on PATH for SQLite DuckDB CLI 1.5.6+ for DuckDB AWS CLI for RDS IAM connections

Node.js 22.15 or later within 22.x, or Node.js 24 and later; Bun 1.4.3 also works. Connections come from a DBeaver-compatible workspace (OS default path, or OMNISQL_WORKSPACE) or a JSON file in OMNISQL_CONFIG_FILE. npx -y omnisql-mcp@latest install adds it to Claude Code, Codex or OpenCode. RDS IAM connections need an AWS CLI session for the saved profile.

Limits

Not covered Engines other than PostgreSQL and its compatibles, MySQL/MariaDB, SQL Server, Oracle, SQLite, DuckDB and ClickHouse return an error
Read only Read-only by default: write and transaction tools stay hidden until OMNISQL_READ_ONLY=false
Size cap execute_query returns 1,000 rows by default and caps maxRows at 100,000; export_data defaults to 10,000 and caps at 1,000,000
Not covered Explicit transactions work on PostgreSQL, MySQL/MariaDB and SQL Server only, not on Oracle
Limit Blocks DROP DATABASE/SCHEMA, TRUNCATE, GRANT/REVOKE, user management and DELETE/UPDATE without WHERE
Limit DuckDB opens existing local files only and needs DuckDB CLI 1.5.6 or later
Limit A name in OMNISQL_DISABLED_TOOLS that is not one of its tools stops it with an error at startup
Limit OMNISQL_CLI_PATH is still read but has no effect since the external CLI fallback was removed

Works only from connections stored in a DBeaver-style workspace; it cannot take a connection string directly. Engines outside the native four depend on an external CLI, with results the project calls variable. Query validation blocks DROP DATABASE/SCHEMA, TRUNCATE, GRANT/REVOKE and DELETE/UPDATE without WHERE. SSH tunnels, AWS RDS IAM sign-in, OMNISQL_PROJECT and the connection/database override are described in the GitHub README but are not in the npm 2.0.1 README or build, so they are not yet released.

Who it suits

Suits developers who keep database connections in DBeaver or a compatible client, or who are willing to write a small JSON config, and want an assistant to look at schemas, run queries or draft migrations across several engines. Because it starts read-only, a reader can try it on shared data first and turn writes on later with OMNISQL_READ_ONLY=false. Pair that with a read-only database user for production, as its docs advise. Pick something else if your engine is not one of the seven it supports, or if you need explicit transactions on Oracle.

Tools 26

17 only read, 5 change things, 4 can delete or overwrite. A ? marks an optional parameter.

list_connections: Lists the connections it can seeincludeDetails?: boolean
list_databases: Lists databases reachable through a saved PostgreSQL, MySQL/MariaDB, SQL Server or ClickHouse connectionconnectionId: string
get_connection_info: Shows details of one saved connectionconnectionId: string
test_connection: Checks that a connection can be reachedconnectionId: stringdatabase?: string
execute_query: Runs a read-only statement, 1,000 rows by defaultconnectionId: stringquery: stringmaxRows?: integerdatabase?: string
write_query deletes: Runs INSERT, UPDATE or DELETE statementsconnectionId: stringquery: stringdatabase?: string
export_data: Returns query results as CSV or JSON, optionally compressedconnectionId: stringquery: stringformat?: enumcompression?: enumincludeHeaders?: booleanmaxRows?: integerdatabase?: string
read_result: Reads a page of rows and columns from a stored resultresultId: stringoffset?: integerlimit?: integercolumnOffset?: integercolumnLimit?: integer
read_result_cell: Reads one long cell of a stored result in chunksresultId: stringrow: integercolumn: integeroffset?: integerlength?: integer
read_export: Reads a stored export as base64 chunksresultId: stringoffset?: integerlength?: integer
list_tables: Lists tables and, optionally, viewsconnectionId: stringschema?: stringincludeViews?: booleandatabase?: string
get_table_schema: Shows a table's columns, indexes and constraintsconnectionId: stringtableName: stringincludeIndexes?: booleandatabase?: string
get_table_stats: Gives catalog row estimates and storage size without scanning the tableconnectionId: stringtableName: stringdatabase?: string
create_table changes: Runs a CREATE TABLE statementconnectionId: stringquery: stringdatabase?: string
alter_table deletes: Runs an ALTER TABLE statementconnectionId: stringquery: stringdatabase?: string
drop_table deletes: Drops a table once confirm is trueconnectionId: stringtableName: stringconfirm: booleandatabase?: string
begin_transaction changes: Opens a transaction on a connectionconnectionId: stringdatabase?: string
execute_in_transaction deletes: Runs a statement inside an open transactiontransactionId: stringquery: string
commit_transaction changes: Commits an open transactiontransactionId: string
rollback_transaction changes: Rolls back an open transactiontransactionId: string
explain_query: Shows a query's execution plan, optionally with ANALYZEconnectionId: stringquery: stringanalyze?: booleanformat?: enumdatabase?: string
compare_schemas: Diffs two connections' schemas and can draft a migration scriptsourceConnectionId: stringtargetConnectionId: stringincludeMigrationScript?: boolean
get_pool_stats: Reports connection pool usageconnectionId: stringdatabase?: string
get_database_stats: Reports size and other statistics for a databaseconnectionId: stringdatabase?: string
append_insight changes: Saves an analysis note, optionally tagged or tied to a connectioninsight: stringconnection?: stringtags?: array
list_insights: Lists saved notes, filtered by connection or tagsconnection?: stringtags?: array

Popularity

43 popularity score, on our list (the bar is 36)

★ 90 ↓ 258/wk

GitHub stars	90	23.5 points
npm downloads, last week	258	19.3 points

Measured 2026-11-07. How the score works.

Where it is published

Code	srthkdev/omnisql-mcp ★ 90
npm	omnisql-mcp 3.0.0, 2026-10-21

What it can reach

Runs	On your machine
Reaches	A database, Files on your machine, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-10-23

Runs on your machine over stdio. It reads your DB client workspace or the JSON config, decrypts saved database and SSH passwords, and connects over the network to the databases they name. It is read-only unless OMNISQL_READ_ONLY=false, and connections from the JSON config also need readOnly set to false before writes are allowed. OMNISQL_ALLOWED_CONNECTIONS limits which connections are visible. A built-in validator blocks some destructive statements, and the docs say it is a safeguard, not a sandbox, and advise a read-only database user. SSH hosts must match known_hosts unless OMNISQL_SSH_STRICT_HOST_KEY=false. Once a day it asks registry.npmjs.org for the latest version unless OMNISQL_UPDATE_NOTIFIER=false. Notes go to a private folder under ~/.cache/omnisql-mcp.

Over time

GitHub stars 90 +6 (+7 %)

9084

13 Oct 20267 Nov 2026

npm downloads a week 258 +177 (+219 %)

1.9k42

27 Apr 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 43 −6 (−13 %)

4938

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-31.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![OmniSQL MCP on EveryMCPServer](https://everymcpserver.com/badge/omnisql-mcp.svg)](https://everymcpserver.com/servers/omnisql-mcp)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 26

Similar servers

MCPQL

MCP Toolbox for Databases

Dremio MCP Server

MySQL MCP Server

dbt MCP Server

PostgreSQL MCP Server