OmniSQL MCP

ユニバーサルデータベース MCP サーバー — ローカルの DB クライアントワークスペースに保存済みの接続を使用して、AI アシスタントにデータベースへの読み取り/書き込みアクセスを提供します（DBeaver 互換）。

これは srthkdev/omnisql-mcp のフォークで、SSH トンネル / ジャンプホストサポートを追加しています。npm には公開されていません — このリポジトリからビルドしてください（インストール を参照）。

対応データベース

ネイティブ対応（ダイレクトドライバ、高速）:

• PostgreSQL（pg 経由）

• MySQL / MariaDB（mysql2 経由）

• SQL Server / MSSQL（mssql 経由）

• SQLite（sqlite3 CLI 経由）

• Trino / Presto（trino-client 経由）

Postgres 互換（pg ドライバ経由で自動的にルーティング）:

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

その他のデータベース: OMNISQL_CLI_PATH で設定された外部 CLI にフォールバックします。結果は CLI によって異なります。

Related MCP server: DBHub

機能

• ローカルの DB クライアントワークスペースで設定済みの接続を再利用 — 重複設定は不要

• SSH トンネル / ジャンプホストの自動サポート: 接続に設定されているものと同じ SSH トンネルおよびゲートウェイ/ジャンプホストプロファイルを介して透過的に接続します（チェーンされたジャンプサーバーを含む）。別途トンネルを設定する必要はありません

• PostgreSQL、MySQL/MariaDB、SQLite、SQL Server、Trino/Presto 向けのネイティブクエリ実行

• 設定可能なプールサイズとタイムアウトを備えたコネクションプーリング（SQLite と Trino/Presto はクエリごとに接続を持たないため、プーリングは適用されません）

• トランザクションサポート（BEGIN/COMMIT/ROLLBACK）

• クエリ実行プランの分析（EXPLAIN）

• マイグレーションスクリプト生成を伴う接続間のスキーマ比較

• execute_query で SELECT のみを強制する読み取り専用モード

• アクセス可能なデータベースを制限する接続ホワイトリスト

• 特定の操作を無効化するツールフィルタリング

• 危険な操作（DROP DATABASE、TRUNCATE、WHERE なしの DELETE/UPDATE）をブロックするクエリ検証

• CSV/JSON へのデータエクスポート

• コネクションプールのクリーンアップを伴うグレースフルシャットダウン

必要条件

• Node.js 18+

• 接続が 1 つ以上設定されているローカル DB クライアント（DBeaver 互換）

インストール

このフォークは npm に公開されていません — ソースからビルドしてください:

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

次に、ビルド済みサーバーをリンクして、omnisql-mcp コマンドがそれを指すようにします:

npm install -g .

npm install -g omnisql-mcp を単独で実行しないでください。 それを行うと npm レジストリから元のアップストリームパッケージがインストールされますが、それには SSH トンネル / ジャンプホストサポートはありません。このリポジトリをクローンしてローカルでビルドし、上記のようにクローンしたフォルダ内で npm install -g . を実行してください。

設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します（macOS）:

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

Claude Code

~/.claude/settings.json に追加します:

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

Cursor

Cursor の設定 > MCP サーバー に追加します:

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

グローバルインストールなしの場合

npm install -g . を実行したくない場合は、代わりに MCP クライアントからビルド済みエントリポイントを直接指定してください:

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

環境変数

読み取り専用モード

すべての書き込み操作をブロックします。execute_query ツールは SELECT、EXPLAIN、SHOW、DESCRIBE ステートメントのみを許可します。トランザクションツールは完全に無効化されます。

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

接続ホワイトリスト

表示されるワークスペース接続を制限します。接続 ID または表示名をカンマ区切りで受け付けます:

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

特定のツールの無効化

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

利用可能なツール

接続管理

• list_connections - すべてのデータベース接続を一覧表示

• get_connection_info - 接続の詳細を取得

• test_connection - 接続性をテスト

データ操作

• execute_query - 読み取り専用クエリを実行（SELECT、EXPLAIN、SHOW、DESCRIBE のみ）

• write_query - INSERT/UPDATE/DELETE を実行

• export_data - CSV/JSON にエクスポート

スキーマ管理

• list_tables - テーブルとビューを一覧表示

• get_table_schema - テーブル構造を取得

• create_table - テーブルを作成

• alter_table - テーブルを変更

• drop_table - テーブルを削除（確認が必要）

トランザクション

• begin_transaction - 新しいトランザクションを開始

• execute_in_transaction - トランザクション内でクエリを実行

• commit_transaction - トランザクションをコミット

• rollback_transaction - トランザクションをロールバック

クエリ分析

• explain_query - クエリ実行プランを分析

• compare_schemas - 2 つの接続間でスキーマを比較

• get_pool_stats - コネクションプールの統計情報を取得

SSH トンネル / ジャンプホスト

• get_ssh_tunnel_info - 接続に関連付けられた SSH トンネル / ジャンプホストプロファイルを確認（マスク表示、秘密情報は含まれません）

その他

• get_database_stats - データベースの統計情報

• append_insight - 分析ノートを保存

• list_insights - 保存されたノートを取得

セキュリティ

• 読み取り専用の強制: execute_query は読み取り専用ステートメント（SELECT、EXPLAIN、SHOW、DESCRIBE、PRAGMA）のみを受け付けます。書き込み操作は write_query を使用する必要があります。

• クエリ検証: DROP DATABASE、DROP SCHEMA、TRUNCATE、WHERE なしの DELETE/UPDATE、GRANT、REVOKE、およびユーザー管理ステートメントをブロックします。

• 接続ホワイトリスト: OMNISQL_ALLOWED_CONNECTIONS を使用して公開される接続を制限します。

• ツールフィルタリング: OMNISQL_DISABLED_TOOLS を使用して任意のツールを無効化できます。

• 入力サニタイズ: 接続 ID と SQL 識別子はインジェクションを防ぐためにサニタイズされます。

• 推奨事項: 本番環境では、多層防御としてデータベースレベルの読み取り専用ユーザーも使用してください。

ワークスペース形式のサポート

DBeaver 互換 DB クライアントが書き込む両方の構成形式をサポートします:

• レガシー: .metadata/.plugins/org.jkiss.dbeaver.core/ 内の XML 構成

• モダン: General/.dbeaver/ 内の JSON 構成

認証情報はワークスペースの credentials-config.json から自動的に復号化されます。

SSH トンネル / ジャンプホストのサポート

接続に SSH トンネル（ネットワークハンドラ）が DB クライアントで設定されている場合 — 1 つ以上のチェーンされたジャンプサーバー / ゲートウェイホストを含む — すべてのネイティブクエリ、test_connection、トランザクション、およびプールされた接続は、そのトンネルを介して透過的にルーティングされます。別途トンネルを設定する必要はありません。サーバーは、DB クライアントが使用するのと同じ SSH ホップチェーンを通じてローカルポートフォワードを開き、ネイティブドライバ（pg、mysql2、mssql）をそのローカルエンドポイントに接続します。

• ホップごとのパスワード認証、公開鍵認証、SSH エージェント認証をサポート

• チェーンされたジャンプサーバーをサポート（localhost -> jump host(s) -> final SSH host -> database）

• トンネルは接続ごとに 1 回開かれ、複数のクエリ間で再利用されます。シャットダウン時に閉じられます

• get_ssh_tunnel_info を使用すると、秘密情報を公開せずに接続のトンネル/ジャンプホストプロファイル（ホスト、ポート、認証タイプ、ジャンプサーバー数）を確認できます

• パスワードまたは鍵パスフレーズをワークスペースの暗号化された認証情報ストアから復元できない場合は、フォールバックとして OMNISQL_SSH_PASSWORD、OMNISQL_SSH_PASSPHRASE、または OMNISQL_SSH_PRIVATE_KEY_PATH を設定してください

Trino / Presto のサポート

Trino 接続は、接続用に保存済みの同じホスト/ユーザー/パスワードを使用して HTTPS/HTTP（Basic 認証）で動作します。Trino 固有の注意点をいくつか示します:

• カタログ/スキーマはオプションです。 接続にデフォルトのカタログ/スキーマが設定されていない場合（DBeaver で複数のカタログを参照する際によくあります）、クエリはテーブルを catalog.schema.table として完全修飾する必要があります。

• list_tables と get_table_schema は設計上カタログに依存しません（system.jdbc.tables/system.jdbc.columns 経由）。そのためデフォルトカタログなしでも動作します。ただし、大規模なマルチカタログクラスターではすべてのカタログにわたってメタデータをスキャンするため、低速になる可能性があり、同じテーブル名が複数のカタログ/スキーマに存在する場合は重複行が返されることがあります。高速で曖昧さのない検索には、代わりに DESCRIBE catalog.schema.table を指定した execute_query を使用してください。

• SSH トンネリング（上記）は、Trino 接続でも他のドライバと同様に機能します。

• このサーバーでは Trino に永続的なセッション/トランザクションモデルはありません — begin_transaction とコネクションプーリングは Trino 接続では利用できません（SQLite と同じです）。

開発

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

ライセンス

MIT