Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
claude mcp add omnisql-mcp -- npx -y omnisql-mcp@3.0.1In einem Terminal ausführen.
{ "mcpServers": { "omnisql-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
Database MCP server with direct multi-instance setup, read-only policies, bounded results, and optional DBeaver connection import
| Read database and SSH settings from DBeaver-compatible workspaces, including custom projects. |
| Query across engines | PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle, DuckDB, and ClickHouse. |
| Choose another database | Discover databases and select one at call time, using the same saved server credentials. |
| Understand your data | Browse tables, inspect columns, explain queries, export CSV/JSON, and compare schemas. |
| Control access | Choose read-only mode, restrict connections, or disable tools. |
| Set up your client | One guided command for Claude Code, Codex, and OpenCode. |
Supported execution paths:
pg)mysql2)mssql)sqlite3 CLI)oracledb)Postgres-compatible (routed through pg driver automatically):
Other databases: Unsupported drivers return an explicit error. External GUI/CLI query fallback has been removed so access and output policies remain enforceable.
DuckDB uses an installed CLI so its native binary stays out of the npm package. Install it with brew install duckdb on macOS, or use the official downloads. Set OMNISQL_DUCKDB_CLI if the executable is outside your MCP client's PATH. See database support for configuration and limits.
Custom drivers wrapping any of the above are detected automatically — see Custom and IAM-Authenticated Drivers.
Run the guided installer, choose Claude Code, Codex, or OpenCode, and OmniSQL adds itself to that client's MCP configuration:
npx -y omnisql-mcp@latest install
The installer detects clients and offers direct database setup, an existing OmniSQL config, or selected DBeaver connections. Add multiple instances to one MCP server, each with its own read-only setting and table rules. Direct setup uses verified TLS by default; passwords are masked and saved only in a private local config (0600 on Unix), or referenced through environment variable names. No OmniSQL API key is needed. An agent with unrestricted file access can still read local config files. Start a new client session after setup.
To add it to a specific client directly:
npx -y omnisql-mcp@latest install claude
npx -y omnisql-mcp@latest install codex
npx -y omnisql-mcp@latest install opencode
Registrations default to read-only. install <client> opens guided setup in a terminal. For noninteractive setup, provide --config /path/to/connections.json, or --workspace /path/to/workspace --allow dev,analytics for selected saved connections. Explicit config excludes workspace discovery. --dry-run previews registration; setup refuses to overwrite an existing entry or use symlink destinations.
--allow-writes enables write tools. Direct JSON connections also need readOnly: false; imported connections retain their saved flag. Database grants and operator policy still apply. SSH requires a verified known_hosts entry by default; OMNISQL_SSH_STRICT_HOST_KEY=false explicitly allows unknown hosts for legacy setups.
You can also register the server using your client's own CLI:
# Claude Code — available across projects
claude mcp add --transport stdio --scope user omnisql --env OMNISQL_CONFIG_FILE=/absolute/path/connections.json -- npx -y omnisql-mcp@latest
# Codex
codex mcp add omnisql --env OMNISQL_CONFIG_FILE=/absolute/path/connections.json -- npx -y omnisql-mcp@latest
# OpenCode v2 — available across projects
opencode mcp add omnisql --global -- npx -y omnisql-mcp@latest
These follow the Claude Code, Codex, and OpenCode v2 registration commands. OpenCode v1 users can add a local server through their MCP settings.
Add the following MCP entry to Claude Desktop's claude_desktop_config.json, or Cursor's mcp.json:
{
"mcpServers": {
"omnisql": {
"command": "npx",
"args": ["-y", "omnisql-mcp@latest"],
"env": { "OMNISQL_CONFIG_FILE": "/absolute/path/connections.json" }
}
}
}
On Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "omnisql-mcp@latest"] when your client cannot launch npx directly.
For a local executable, including machines without Node.js:
curl -fsSL https://omnisql.srthkdev.com/install.sh | bash
Installs under ~/.local/share/omnisql-mcp with a launcher at ~/.local/bin/omnisql-mcp, without sudo. If Bun 1.4.3+ is unavailable, it downloads a private Bun runtime and verifies its SHA-256 checksum. Use the printed absolute launcher path as your MCP client's command. Run the installer again to upgrade; append bash -s -- 3.0.0 in place of bash to pin a version. OMNISQL_INSTALL_DIR and OMNISQL_BIN_DIR choose other directories.
Register OmniSQL once. Select connectionId in each tool call; select database to switch databases on PostgreSQL, MySQL/MariaDB, SQL Server, or ClickHouse. Each instance can have its own read-only setting, table policy, credentials, timeout, row/byte limits, and pool size.
Set OMNISQL_CONFIG_FILE to your JSON configuration, or reuse discovered workspace connections. Explicit connections default to read-only. See the multi-instance configuration guide and access policies.
Large results use private, expiring handles with row and column pagination. Long cells and large exports can be read in bounded chunks. See result paging.
Enabled by default and blocks all write operations. The execute_query tool only allows SELECT, EXPLAIN, SHOW, and DESCRIBE statements. Transaction tools are disabled entirely.
{
"mcpServers": {
"omnisql": {
"command": "npx",
"args": ["-y", "omnisql-mcp@latest"],
"env": {
"OMNISQL_READ_ONLY": "true"
}
}
}
}
Restrict which workspace connections are visible. Accepts connection IDs or display names, comma-separated:
{
"mcpServers": {
"omnisql": {
"command": "npx",
"args": ["-y", "omnisql-mcp@latest"],
"env": {
"OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
}
}
}
}
{
"mcpServers": {
"omnisql": {
"command": "npx",
"args": ["-y", "omnisql-mcp@latest"],
"env": {
"OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
}
}
}
}
list_connections - List all database connectionslist_databases - Discover accessible databases on PostgreSQL, MySQL/MariaDB, SQL Server, and ClickHouseget_connection_info - Get connection detailstest_connection - Test connectivityexecute_query - Run read-only queries (SELECT, EXPLAIN, SHOW, DESCRIBE only)write_query - Run INSERT/UPDATE/DELETEexport_data - Export to CSV/JSON, with optional gzip, Brotli, or zstdread_result - Read a page of stored rows and columnsread_result_cell - Read a long cell in chunksread_export - Read a stored export in bounded base64 chunksExports support optional gzip, Brotli, and zstd downloads through export_data.compression. Ordinary queries remain paginated JSON. Measured compression and media changes.
list_tables - List tables and viewsget_table_schema - Get columns, indexes, and constraintsget_table_stats - Get catalog row estimates and data/index storagecreate_table - Create tablesalter_table - Modify tablesdrop_table - Drop tables (requires confirmation)PostgreSQL, MySQL/MariaDB, and SQL Server support explicit transactions. Results obey the same row/byte limits and pagination as ordinary queries. Each transaction accepts one operation at a time; a failed query or changed connection/access policy rolls it back. Schema operations are excluded because some engines commit DDL implicitly. At most 32 transactions may be active or starting; idle transactions expire after one hour.
begin_transaction - Start a new transactionexecute_in_transaction - Execute query within a transactioncommit_transaction - Commit a transactionrollback_transaction - Roll back a transactionexplain_query - Analyze query execution plancompare_schemas - Compare schemas between two connectionsget_pool_stats - Get connection pool statisticsget_database_stats - Database statisticsappend_insight - Store analysis noteslist_insights - Retrieve stored notesexecute_query only accepts read-only statements (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Write operations must use write_query.OMNISQL_ALLOWED_CONNECTIONS.OMNISQL_DISABLED_TOOLS.Supports both configuration formats written by DBeaver-compatible DB clients:
.metadata/.plugins/org.jkiss.dbeaver.core/General/.dbeaver/The project/workspace folder name (General by default) is configurable via OMNISQL_PROJECT,
so workspaces using a custom or renamed DBeaver project (e.g. DataPlatform) are discovered
without needing to rename the project or symlink the folder.
DBeaver connections are configured either manually (host, port, database fields) or by
URL (a JDBC URL). Both work. In URL mode DBeaver leaves the host/port fields at placeholder
values — usually localhost — and reads only the URL, so the URL is what is used here too.
Connections that DBeaver reaches through an SSH tunnel are tunneled here as well. The tunnel is opened on first use and reused for the lifetime of the server, with a loopback-only local forward, and the connection's host/port are treated the way DBeaver treats them: as the database as seen from the SSH server.
SSH_AUTH_SOCK set in the MCP server's environment. MCP clients
usually do not inherit your shell, so set it explicitly in the client's server config if you
use an agent.known_hosts; unknown hosts are refused by default.
Verify the host fingerprint through a trusted channel before adding it.
OMNISQL_SSH_STRICT_HOST_KEY=false allows unknown hosts explicitly; known-host mismatches still fail.Table policies resolve real catalog names before checking access, including engine-specific case rules. Qualified denies also cover unqualified SQL; paged results and exports recheck permissions on every read. Restricted queries stay inside the selected database. See access rules for configuration and limits.
Use list_databases with a saved connectionId to discover databases accessible on a PostgreSQL, MySQL/MariaDB, SQL Server, or ClickHouse instance. Pass an optional database to execute_query, export_data, explain_query, list_tables, get_table_schema, get_database_stats, test_connection, or get_pool_stats:
{"connectionId": "my-pg-server", "database": "app_logs", "query": "SELECT count(*) FROM log"}
The saved host, credentials, IAM, TLS, and SSH settings are reused. The saved connection is unchanged and pools remain separate for each database. The existing connectionId: "my-pg-server/app_logs" shorthand also works. File-backed engines such as SQLite require a separate saved connection for each file. Read-only checks and connection whitelists still apply; list a connection ID to allow its databases, or connectionId/database entries to restrict access to specific databases.
Oracle runs through oracledb in Thin mode, so no Oracle Client is needed. Service names, SIDs,
TNS aliases and connect descriptors are read from the connection. Rows are capped by the driver,
using a bounded ResultSet fetch. Ordinary queries reuse an isolated, bounded pool; privileged sessions remain standalone. Explicit multi-call Oracle transactions are not available.
Native routing normally keys off the driver id (postgres-jdbc, mysql8). Custom drivers often use an
opaque id instead — a UUID, say — which names no engine. Those connections are resolved by falling back
to the connection's provider (postgresql, mysql, …) and then to the JDBC URL's sub-protocol,
including wrapped ones such as jdbc:aws-wrapper:postgresql://…. A custom driver wrapping a supported
engine therefore works with no extra configuration.
If an engine still cannot be identified, the resulting error names both the driver id and the provider so you can see what was missing.
Connections that authenticate with an RDS IAM token instead of a stored password are detected and handled automatically. Both shapes are recognised:
wrapperPlugins: "iam" alongside awsProfile
and iamRegion.For these connections OmniSQL:
aws rds generate-db-auth-token (via the AWS CLI, so SSO and role-chained
profiles work as configured) and uses it as the password.<profile>-<user>) or the
assumed SSO session name.Requirements: the AWS CLI on PATH (or OMNISQL_AWS_CLI_PATH), a valid session for the
connection's profile (aws sso login --profile <profile>), and network reachability to the endpoint.
An expired SSO session produces an error naming the profile to re-authenticate.
The recording above captures a real Codex CLI session calling OmniSQL tools. It uses synthetic customers and orders from the isolated .demo/ workspace. The integration script below creates the SQLite fixtures, then checks discovery, schema inspection, queries, exports, query plans, schema comparison, and blocked writes.
bun install --frozen-lockfile
bun run build
bun run demo
To also test PostgreSQL database discovery, database selection, and pool identities against a temporary local cluster:
OMNISQL_DEMO_PG_BIN=/path/to/postgres/bin bun run demo -- --postgres
The PostgreSQL cluster binds to loopback on a temporary port, uses a random password, and is stopped and deleted after the run. The SQLite examples stay under .demo/ so you can connect a client to them. Existing workspaces are untouched. Watch the Codex CLI session. See recording details.
Node setup registers npx -y omnisql-mcp@latest; Bun setup registers the current Bun executable with x --bun --yes omnisql-mcp@latest; restart the MCP client to pick up a new version. Running servers keep their current version until restarted. OmniSQL checks npm at most once a day and writes a short update notice to stderr when a newer version is available. The check sends no database settings or credentials. Set OMNISQL_UPDATE_NOTIFIER=false to disable it. Standalone installs update by rerunning the curl installer.
Bun 1.4.3 is the development runtime and package manager. bun.lock covers the server and website workspace. Builds transpile with Bun; bun run typecheck remains required because transpilation does not check types. The published JavaScript also runs on Node 22+ for existing npm clients.
git clone https://github.com/srthkdev/omnisql-mcp.git
cd omnisql-mcp
bun install --frozen-lockfile
bun run build
bun run test
bun run lint
CI builds with Bun 1.4.3, runs native Bun tests, verifies the packed MCP server on Bun and Node.js 22/24/26, and checks dependencies. Seeded database and TLS fixtures run on both Bun and Node. It does not publish to npm.
Maintainers release from a clean checkout after CI passes:
bun install --frozen-lockfile
bun run lint
bun run typecheck
bun run test
bun run build
bun run test:package
bun audit --audit-level=high
npm login
npm publish --access public
git tag vX.Y.Z
git push origin vX.Y.Z
Update the package version and changelog before publishing. Pushing the version tag creates the GitHub release; attach the release notes from the changelog. npm pack rebuilds dist/ before packaging.
MIT
Database MCP server with direct multi-instance setup, read-only policies, bounded results, and optional DBeaver connection import
{ "mcpServers": { "omnisql-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Omnisql läuft lokal über stdio.
Zuletzt geprüft: 2026-11-15. Database MCP server with direct multi-instance setup, read-only policies, bounded results, and optional DBeaver connection import