Vertica Mcp

Vertica MCP サーバー

MCP クライアントを Vertica に接続して、データのクエリ、テーブル構造の確認、ビューやプロジェクションの調査を行います。**デフォルトでは読み取り専用です。**接続は初回使用時に開かれ、アイドル状態になるまで再利用されます。サーバーは stdio 経由で通信します。

既存のクライアント設定、環境変数名、ツール名、CLI エイリアスは引き続き使用できます。意図的なバグ修正と安全上の制限については、アップグレードに関する注意事項をご覧ください。

クイックスタート

Node.js 20 以降と、Vertica データベースへのネットワークアクセスが必要です。可能な場合は、現在サポートされている Node LTS リリースを使用してください。

環境ファイルを作成します（.env.exampleを参照）。

VERTICA_HOST=your-vertica-host
VERTICA_PORT=5433
VERTICA_DATABASE=your_database
VERTICA_USER=readonly_user
VERTICA_PASSWORD=your_password

MCP クライアントの設定に追加します。この形式は、Claude Desktop、Cursor、および stdio サーバーを起動するその他のクライアントで使用できます。

{
  "mcpServers": {
    "vertica-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@hechtcarmel/vertica-mcp@latest",
        "--env-file",
        "/absolute/path/to/vertica.env"
      ]
    }
  }
}

Claude Code の場合：

claude mcp add vertica --scope user -- npx -y @hechtcarmel/vertica-mcp@latest --env-file /absolute/path/to/vertica.env

クライアントの env 設定を通じて、VERTICA_* 変数を直接指定することもできます。プロセス環境の値は環境ファイルより優先されます。--env-file を指定しない場合、サーバーは作業ディレクトリから .env を読み込みます。明示的に指定したファイルは読み取り可能である必要があります。-e、-h／--help、-v／--version は引き続きサポートされます。インストール後は、vertica-mcp と元のスコープ付きバイナリエイリアスの両方を使用できます。

ツール

ツール	引数	結果
execute_query	sql、params（省略可能）	行、フィールド、行数、元のクエリ
stream_query	sql、params（省略可能）、batchSize、maxRows	バッチ、合計行数、件数、切り捨て状態
list_tables	schemaName（省略可能）	テーブル、型、所有者
list_views	schemaName（省略可能）	ビューのプレビューと完全な定義
list_indexes	tableName、schemaName（省略可能）	Vertica のプロジェクションとその列
get_table_structure	tableName、schemaName（省略可能）	列、NULL 許容性、制約、所有者

カタログツールに渡す名前は、大文字・小文字や空白も含めて正確に指定してください。SQL の引用符で囲まないでください。スキーマを省略すると、VERTICA_DEFAULT_SCHEMA（public）が使用されます。すべてのカタログフィルターではバインドパラメーターを使用します。

パラメーター化クエリの呼び出し例：

{
  "sql": "SELECT customer_name FROM public.customers WHERE customer_id = ? LIMIT 10",
  "params": [42]
}

ドライバーでは ? プレースホルダーを使用します。値は順番に指定し、SQL に直接埋め込まないでください。パラメーターで表せるのは値であり、テーブル名や列名などの識別子ではありません。

JavaScript の安全な範囲内の INTEGER 値は数値として扱われます。範囲を超える 64 ビット整数は、精度を維持するために 10 進数文字列として扱われます。フィールドメタデータには、実際の Vertica 型の名前と ID、およびワイヤ形式が含まれます。

結果は元の JSON テキストを content に保持し、一致する structuredContent も提供します。データベースエラーおよびポリシーエラーでは、MCP の isError: true と success: false が設定されます。検出およびヘルプ／バージョンコマンドは Vertica に接続しません。

入力スキーマでは、未対応のページネーションや行数制限のオプションを含め、未知の引数名は拒否されます。宣言された引数のみを使用してください。出力スキーマでは成功と失敗を区別し、行、フィールド、メタデータ、件数、切り捨てについて記述します。execute_query.rowCount は書き込みによる影響行数ではなく、返された結果行数を数えます。list_indexes.indexCount は個別のプロジェクション数ではなく、プロジェクションの列エントリー数を数えます。

カタログツールでは、固定クエリの読み取り専用動作が明示されています。任意の SQL を実行する 2 つのツールでは、保守的な注釈が使用されます。関数には副作用がある可能性があるため、サーバーは純粋性、冪等性、または閉じた対話世界を保証しません。これは、デフォルトの読み取り専用ポリシーを無効にするものではありません。これらのツールの _meta["com.hechtcarmel.vertica/readOnlyTransaction"] は、読み取り専用トランザクションが設定されているかどうかを示します。ツール契約のレビューを参照してください。

大きな結果のバッチ処理

{
  "sql": "SELECT customer_id, customer_name FROM public.customers ORDER BY customer_id",
  "batchSize": 1000,
  "maxRows": 10000
}

stream_query は、SELECT/WITH クエリを外側に上限付きの LIMIT を付けて一度だけ実行し、結果をバッチに分割します。すでに LIMIT/OFFSET や末尾のセミコロンを含むクエリも受け付けます。batchSize より小さい場合も maxRows が優先されます。切り捨てを検出するため、追加で 1 行を取得します。

• batchSize：1～10,000。デフォルトは 1,000 です。
• maxRows：1～1,000,000。省略した場合は batchSize × 100 がデフォルトとなり、上限は 1,000,000 です。
• truncated とトップレベルの hasMore：追加の行が存在する場合は true になります。
• batchCount と totalRows：実際に返されるバッチ数と行数です。

このツールは1 つの MCP レスポンスを返します。トランスポートメッセージを段階的にストリーミングしたり、継続カーソルを提供したりはしません。行はメモリ上に展開されます。上限はバイト数ではなく行数で適用されます。小さな上限を指定し、必要な列だけを選択してください。順序を再現可能にするには ORDER BY を使用してください。SQL の実行に上限のない execute_query を使う場合、大きなクエリには LIMIT を追加してください。

list_indexes は従来の名前と出力フィールドを維持しています。Vertica は従来型のインデックスではなくプロジェクションを使用します。isUnique は、独立した一意性の証明ではなく、カタログの is_key_constraint_projection フラグを反映します。list_views.definition は従来どおり 200 文字のプレビューを返し、fullDefinition には完全な SQL が含まれます。

設定

必須項目は VERTICA_HOST、VERTICA_DATABASE、VERTICA_USER です。 VERTICA_PASSWORD は省略可能です（たとえば、データベースが trust 認証を使用する場合）。

変数	デフォルト	意味
VERTICA_PORT	5433	TCP ポート。1～65535
VERTICA_READONLY_MODE	true	読み取り専用のクエリポリシーとトランザクション
VERTICA_QUERY_TIMEOUT	60000	接続とクエリのタイムアウト（ミリ秒）。1000～300000
VERTICA_IDLE_TIMEOUT	3600000	アイドル切断までの時間（ミリ秒）。60000～86400000
VERTICA_SSL	false	有効にすると、暗号化された TLS を必須にします
VERTICA_SSL_REJECT_UNAUTHORIZED	true	TLS が有効な場合に証明書とホスト名を検証します
VERTICA_DEFAULT_SCHEMA	public	カタログツールのデフォルトスキーマ
VERTICA_CONNECTION_LOAD_BALANCE	false	初回接続時にクラスターが指定するノードを試します
VERTICA_DEBUG または DEBUG	未設定	true にすると、設定診断情報を stderr に出力します。パスワードは伏せられます

ブール値のオプションは true、false、1、0 を受け付けます（大文字と小文字は区別されません）。無効な値を指定すると、設定の検証に失敗します。

VERTICA_SSL=true の場合、Vertica ドライバーの実際の verify-full モードによって、証明書チェーンとホスト名の両方が検証されます。プライベート CA には NODE_EXTRA_CA_CERTS を使用してください。VERTICA_SSL_REJECT_UNAUTHORIZED=false の場合も TLS は必須ですが、ピア検証は無効になります（require モード）。既存のインストールとの互換性のため、SSL はデフォルトで無効です。

ロードバランシングには DESCRIBE_LOAD_BALANCE_DECISION を使用します。選択された IP への接続に成功した場合に限り、初期接続が置き換えられます。IPv4 と IPv6 に対応しています。ルーティングに失敗した場合、元の接続は引き続き使用できます。リダイレクト先には到達可能である必要があります。また、検証付き TLS では、選択されたノードの IP も受け入れられる必要があります。

読み取り専用の動作

読み取り専用モードでは、SELECT、SHOW、DESCRIBE、EXPLAIN、または読み取り専用の WITH ステートメントを1つだけ実行できます。複数のステートメントを連ねたもの、書き込み可能な CTE、SELECT INTO、および書き込みの EXPLAIN は拒否されます。先頭のコメント、引用符で囲まれた値や識別子、末尾のセミコロンも処理されます。各クエリは Vertica の読み取り専用トランザクション内で実行され、結果の取得後にロールバックされます。ロールバックに失敗すると、クライアントは無効になります。

ステートメントガードは意図的に保守的な設計です。引用符で囲まれていない変更キーワードや、解釈が曖昧なバックスラッシュエスケープなど、通常と異なる有効な SQL が拒否される場合があります。引用符で囲まれた識別子とバインド値を使用してください。これは完全な SQL パーサーでも、任意の関数を対象とするサンドボックスでもありません。Vertica の読み取り専用トランザクションでは、関数によるあらゆる副作用やディスク書き込みを防げるわけではありません。SELECT とスキーマの USAGE 権限のみを持つ、最小権限の専用アカウントを使用し、特権を要する管理関数やユーザー定義関数は避けてください。クエリ結果は信頼できないデータとして扱ってください。

書き込みを明示的に有効にするには、次のようにします。

VERTICA_READONLY_MODE=false

execute_query は、1回の呼び出しにつき書き込みステートメントを1つ受け付けるようになります。stream_query は引き続き SELECT/WITH のみを受け付けます。エラーやタイムアウトが発生しても、SQL が自動的に再実行されることはありません。キャンセルまたはタイムアウトが発生すると、ドライバーの処理を停止するため、該当する接続が閉じられます。書き込み中に処理が中断された場合、結果が不確定になることがあります。書き込みを再試行する前に、データベースの状態を確認してください。

アップグレード

npm パッケージ名、2つのバイナリエイリアス、フラグ、環境変数、6つのツール、引数名、および JSON のテキストフィールドは維持されています。Node 20 以降が必要になりました。意図的な修正については、CHANGELOG.md をご覧ください。

• すべての Boolean 設定で、文字列の false が false として扱われるようになりました。誤記は拒否されます。
• TLS 設定が、ドライバーの実際の TLS モードを設定するようになりました。
• SQL ポリシーにより、プレフィックスチェックの回避が防止されます。スクリプトは個別に呼び出す必要があります。
• ツール呼び出しに失敗した場合、MCP のエラーフラグが設定されるようになりました。
• バッチクエリは1回だけ実行され、制限が適用され、切り捨てが明示的に報告されます。

このバージョンでは、現行の安定版である MCP TypeScript SDK v2 を使用し、SDK の serveStdio エントリーポイントを通じて 2026-07-28 プロトコルを明示的に提供します。initialize ハンドシェイクを使用する旧バージョンのクライアントも動作します。必要な Node の最小バージョンは 20 になりました。開発には Node 24 LTS を使用してください。既存の環境ファイルと読み取り専用のデフォルト設定は引き続きサポートされます。HTTP トランスポートやネットワークリスナーは追加されません。

リリースとローカルでの検証

バージョン管理、GitHub リリースの下書き、チェックサム付きアーティファクト、provenance 付きで別途承認される npm 公開については、リリースプロセスをご覧ください。マージ前に、CI の合格済みアーティファクトと既存の環境ファイルを使用し、Mac 専用の読み取り専用ハンドオフを実施してください。実際のローカル検証では、集計、モック、拒否、書き込みパスのテストスイートを絶対に実行しないでください。

開発とトラブルシューティング

セットアップ、チェック、アーキテクチャ、パッケージの検証、オプトイン方式のデータベース統合テストについては、CONTRIBUTING.mdをご覧ください。

• 接続エラー：ホスト、ポート、認証情報、ネットワークへの接続性、TLS の信頼設定を確認してください。同じアカウントを使って vsql でテストしてください。
• 権限エラー：必要なスキーマやテーブルへのアクセス権のみを付与してください。カタログの検出では、設定済みアカウントから見えるオブジェクトのみが報告されます。
• タイムアウト：クエリを最適化するか、VERTICA_QUERY_TIMEOUT を許容範囲内で引き上げてください。タイムアウトしたクライアントは閉じられ、次回の呼び出し時に新しい接続が開かれます。
• 出力が大きい場合：LIMIT を追加するか、stream_query.maxRows に小さな値を指定してください。行数の上限に達する前に、クライアントのメッセージサイズ制限に達することがあります。
• Stdio のエラー：stdout は MCP 専用です。サーバーの診断情報は stderr に出力されます。絶対パスで環境ファイルを指定し、クライアントのサーバーログを確認してください。

ライセンスと謝辞

MIT。このプロジェクトの元となったプロジェクトは、@nolleh による mcp-vertica です。