Skip to main content
Glama

OmniSQL MCP

Universal database MCP server — give AI assistants read/write access to your databases using connections already saved in your local DB client workspace (DBeaver-compatible).

This is a fork of srthkdev/omnisql-mcp that adds SSH tunnel / jump host support. It is not published to npm — build it from this repo (see Installation).

License: MIT Node.js

Database Support

Natively supported (direct driver, fast):

  • PostgreSQL (via pg)

  • MySQL / MariaDB (via mysql2)

  • SQL Server / MSSQL (via mssql)

  • SQLite (via sqlite3 CLI)

  • Trino / Presto (via trino-client)

Postgres-compatible (routed through pg driver automatically):

  • CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

Other databases: Fall back to an external CLI configured via OMNISQL_CLI_PATH. Results vary by CLI.

Related MCP server: Database MCP Server

Features

  • Reuses connections already configured in your local DB client workspace — no duplicate setup

  • Automatic SSH tunnel / jump host support: transparently connects through the same SSH tunnel and gateway/jump host profile configured on the connection (including chained jump servers), no separate tunnel setup needed

  • Native query execution for PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Trino/Presto

  • Connection pooling with configurable pool size and timeouts (pooling not applicable to SQLite or Trino/Presto, which are connectionless per query)

  • Transaction support (BEGIN/COMMIT/ROLLBACK)

  • Query execution plan analysis (EXPLAIN)

  • Schema comparison between connections with migration script generation

  • Read-only mode with enforced SELECT-only on execute_query

  • Connection whitelist to restrict which databases are accessible

  • Tool filtering to disable specific operations

  • Query validation to block dangerous operations (DROP DATABASE, TRUNCATE, DELETE/UPDATE without WHERE)

  • Data export to CSV/JSON

  • Graceful shutdown with connection pool cleanup

Requirements

  • Node.js 18+

  • A local DB client (DBeaver-compatible) with at least one configured connection

Installation

This fork isn't published to npm — build it from source:

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build

Then link the built server so the omnisql-mcp command points at it:

npm install -g .

Do not run npm install -g omnisql-mcp on its own. That installs the original upstream package from the npm registry, which does not have SSH tunnel / jump host support. You must clone this repo and build it locally, then run npm install -g . from inside the cloned folder as shown above.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Add to Cursor Settings > MCP Servers:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Without a global install

If you'd rather not run npm install -g ., point your MCP client directly at the built entry point instead:

{
  "mcpServers": {
    "omnisql": {
      "command": "node",
      "args": ["/absolute/path/to/omnisql-mcp/dist/index.js"]
    }
  }
}

Environment Variables

Variable

Description

Default

OMNISQL_CLI_PATH

Path to external DB client CLI (used for unsupported-driver fallback)

Unset

OMNISQL_WORKSPACE

Path to local DB client workspace directory

OS default

OMNISQL_TIMEOUT

Query timeout (ms)

30000

OMNISQL_DEBUG

Enable debug logging

false

OMNISQL_READ_ONLY

Disable all write operations

false

OMNISQL_ALLOWED_CONNECTIONS

Comma-separated whitelist of connection IDs or names

All

OMNISQL_DISABLED_TOOLS

Comma-separated tools to disable

None

OMNISQL_POOL_MIN

Minimum connections per pool

2

OMNISQL_POOL_MAX

Maximum connections per pool

10

OMNISQL_POOL_IDLE_TIMEOUT

Idle connection timeout (ms)

30000

OMNISQL_POOL_ACQUIRE_TIMEOUT

Connection acquire timeout (ms)

10000

OMNISQL_SSH_PASSWORD

Fallback SSH password if it can't be read from the workspace

Unset

OMNISQL_SSH_PASSPHRASE

Fallback SSH private key passphrase

Unset

OMNISQL_SSH_PRIVATE_KEY_PATH

Fallback SSH private key file path

Unset

Read-Only Mode

Blocks all write operations. The execute_query tool only allows SELECT, EXPLAIN, SHOW, and DESCRIBE statements. Transaction tools are disabled entirely.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

Connection Whitelist

Restrict which workspace connections are visible. Accepts connection IDs or display names, comma-separated:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

Disable Specific Tools

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

Available Tools

Connection Management

  • list_connections - List all database connections

  • get_connection_info - Get connection details

  • test_connection - Test connectivity

Data Operations

  • execute_query - Run read-only queries (SELECT, EXPLAIN, SHOW, DESCRIBE only)

  • write_query - Run INSERT/UPDATE/DELETE

  • export_data - Export to CSV/JSON

Schema Management

  • list_tables - List tables and views

  • get_table_schema - Get table structure

  • create_table - Create tables

  • alter_table - Modify tables

  • drop_table - Drop tables (requires confirmation)

Transactions

  • begin_transaction - Start a new transaction

  • execute_in_transaction - Execute query within a transaction

  • commit_transaction - Commit a transaction

  • rollback_transaction - Roll back a transaction

Query Analysis

  • explain_query - Analyze query execution plan

  • compare_schemas - Compare schemas between two connections

  • get_pool_stats - Get connection pool statistics

SSH Tunnel / Jump Host

  • get_ssh_tunnel_info - Inspect the SSH tunnel / jump host profile associated with a connection (redacted, no secrets)

Other

  • get_database_stats - Database statistics

  • append_insight - Store analysis notes

  • list_insights - Retrieve stored notes

Security

  • Read-only enforcement: execute_query only accepts read-only statements (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Write operations must use write_query.

  • Query validation: Blocks DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE without WHERE, GRANT, REVOKE, and user management statements.

  • Connection whitelist: Restrict which connections are exposed via OMNISQL_ALLOWED_CONNECTIONS.

  • Tool filtering: Disable any tool via OMNISQL_DISABLED_TOOLS.

  • Input sanitization: Connection IDs and SQL identifiers are sanitized to prevent injection.

  • Recommendation: For production use, also use a database-level read-only user for defense in depth.

Workspace Format Support

Supports both configuration formats written by DBeaver-compatible DB clients:

  • Legacy: XML config in .metadata/.plugins/org.jkiss.dbeaver.core/

  • Modern: JSON config in General/.dbeaver/

Credentials are automatically decrypted from the workspace credentials-config.json.

SSH Tunnel / Jump Host Support

If a connection has an SSH tunnel (network handler) configured in your DB client — including one or more chained jump servers / gateway hosts — every native query, test_connection, transaction, and pooled connection transparently routes through it. No separate tunnel setup is required: the server opens a local port forward through the same SSH hop chain your DB client would use and connects the native driver (pg, mysql2, mssql) to that local endpoint.

  • Supports password, public key, and SSH agent authentication per hop

  • Supports chained jump servers (localhost -> jump host(s) -> final SSH host -> database)

  • Tunnels are opened once per connection and reused across queries; closed on shutdown

  • Use get_ssh_tunnel_info to inspect a connection's tunnel/jump host profile (host, port, auth type, jump server count) without exposing any secrets

  • If a password or key passphrase can't be recovered from the workspace's encrypted credential store, set OMNISQL_SSH_PASSWORD, OMNISQL_SSH_PASSPHRASE, or OMNISQL_SSH_PRIVATE_KEY_PATH as a fallback

Trino / Presto Support

Trino connections work over HTTPS/HTTP (Basic Auth) using the same host/user/password already saved for the connection. A few Trino-specific notes:

  • Catalog/schema are optional. If the connection has no default catalog/schema configured (common when browsing multiple catalogs in DBeaver), queries must fully qualify tables as catalog.schema.table.

  • list_tables and get_table_schema are catalog-agnostic by design (via system.jdbc.tables/system.jdbc.columns), so they work without a default catalog — but on a large multi-catalog cluster this scans metadata across every catalog, which can be slow and may return duplicate rows if the same table name exists in more than one catalog/schema. For a fast, unambiguous lookup, use execute_query with DESCRIBE catalog.schema.table instead.

  • SSH tunneling (above) works the same way for Trino connections as any other driver.

  • Trino has no persistent session/transaction model in this server — begin_transaction and connection pooling are not available for Trino connections (same as SQLite).

Development

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

License

MIT

Available Tools

22 tools
alter_tableB

Modify existing table schema (add columns, rename tables, etc.)

Inputs: query (required), connectionId (required).

append_insightA

Add a business insight or analysis note to the memo

Inputs: insight (required), tags, connection.

begin_transactionC

Start a new database transaction

Inputs: connectionId (required).

commit_transactionB

Commit an active transaction

Inputs: transactionId (required).

compare_schemasB

Compare schemas between two database connections

Inputs: sourceConnectionId (required), targetConnectionId (required), includeMigrationScript.

create_tableB

Create new tables in the database

Inputs: query (required), connectionId (required).

drop_tableA

Remove a table from the database with safety confirmation

Inputs: confirm (required), tableName (required), connectionId (required).

execute_in_transactionB

Execute a query within an active transaction

Inputs: query (required), transactionId (required).

execute_queryA

Execute a SQL query on a specific database connection (read-only queries)

Inputs: query (required), connectionId (required), maxRows.

explain_queryB

Get the execution plan for a SQL query

Inputs: query (required), connectionId (required), format, analyze.

export_dataC

Export query results to various formats (CSV, JSON, etc.)

Inputs: query (required), connectionId (required), format, maxRows, +1 more.

get_connection_infoB

Get detailed information about a specific database connection

Inputs: connectionId (required).

get_database_statsA

Get statistics and information about a database

Inputs: connectionId (required).

get_pool_statsB

Get connection pool statistics for a connection

Inputs: connectionId (required).

get_ssh_tunnel_infoA

Get the SSH tunnel / jump host profile associated with a database connection, as configured in the DB client's workspace (network handler config). Secrets are redacted; use test_connection to verify the tunnel actually connects.

Inputs: connectionId (required).

get_table_schemaB

Get schema information for a specific table

Inputs: tableName (required), connectionId (required), includeIndexes.

list_connectionsB

List all available database connections

Inputs: includeDetails.

list_insightsA

List all stored business insights and analysis notes

Inputs: tags, connection.

list_tablesB

List all tables in a database

Inputs: connectionId (required), schema, includeViews.

rollback_transactionB

Rollback an active transaction

Inputs: transactionId (required).

test_connectionB

Test connectivity to a database connection

Inputs: connectionId (required).

write_queryC

Execute INSERT, UPDATE, or DELETE queries on a specific database connection

Inputs: query (required), connectionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools pair a clear resource with a distinct action, so connection listing, testing, schema inspection, and query execution are easy to separate. The main source of ambiguity is execute_query vs execute_in_transaction (and to a lesser degree write_query), though the descriptions do state read-only vs transactional context.

    Naming Consistency5/5

    All tools use lowercase snake_case with a verb_noun pattern like list_connections, create_table, and commit_transaction. The few phrases like execute_in_transaction or get_ssh_tunnel_info still follow the convention and remain predictable.

    Tool Count3/5

    22 tools is on the heavy side and falls into the 16-25 borderline range. The count is defensible for a broad SQL/connection-management server, but the diagnostic and insight tools make the surface feel larger than a typical focused MCP server.

    Completeness4/5

    The toolset covers the main database lifecycle: connections, read/write SQL, transaction control, table DDL, schema inspection, export, and query planning. Gaps such as creating/deleting connections or managing indexes/views are present, but the core workflows are well supported.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
      17 npm
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides universal database operations for AI assistants through MCP, supporting 40+ databases including PostgreSQL, MySQL, MongoDB, Redis, and SQLite with built-in introspection tools for schema exploration.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely interact with PostgreSQL databases through a standardized MCP interface, supporting SQL queries, schema inspection, and database management.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to explore and query PostgreSQL, MySQL, MariaDB, SQLite, SQL Server and Oracle databases by reusing connections already configured in DBeaver, with no separate credentials to manage. Queries run read-only and rolled back by default, so schema exploration, data reads and query plans are safe on existing dev, test and production connections.
      7
      33 npm
      MIT