valv

@valv/mcp

データベース URL を指定するだけで、エージェントが安全にクエリを実行します。SQL もコードも不要です。

valv を基盤とする、設定不要の MCP サーバーです。接続文字列を渡すと、稼働中のスキーマをイントロスペクションし、4 つのツール（list_resources、search_resources、describe_resource、query）を提供します。デフォルトでは読み取り専用で、ポリシーを適用します。SQL がモデルに渡されることはなく、許可したデータのみを読み取れます。

PostgreSQL、MySQL、SQLite、CockroachDB、ClickHouse、MongoDB に対応しています。

ガイド付きセットアップ

最も手早く始められる方法です。データベースを調べ、アクセス方法を選択して、設定を書き込みます。

npx @valv/mcp init

接続文字列、または個別の接続情報（ホスト、ポート、ユーザー、パスワード、データベース）を入力できます。方言を確認して接続し、テーブルを表示した後、読み取り専用、テーブルの選択、ポリシーファイルのひな形から選べます。続いて、既存の設定をそのまま残しながら、選択したクライアント（Claude Code、Claude Desktop、Cursor、Codex）のプロジェクトまたはグローバルな設定にサーバーのエントリーをマージします。最後に、valv のクエリ方法と、結果をインタラクティブなチャートレポートの HTML ファイルに変換する方法をエージェントに教える valv スキルのインストールを提案します。スキルは、プロジェクトまたはグローバルな場所にある Claude Code 用（.claude/skills）、Codex 用（.agents/skills）、または Cursor 用（.cursor/skills）としてインストールできます。さらに、データベースのスキーマを調べ（今後のクエリに備えて .valv/notes.md に記録し）、データベースの概要を示すインタラクティブな valv-map.html を 1 つ生成するためのキックスタートプロンプトをクリップボードにコピーできます。これをエージェントに貼り付けてください。

手動セットアップ

.mcp.json（または Claude Desktop の設定）に追加します。

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@valv/mcp"],
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb" }
    }
  }
}

ClickHouse の場合は、HTTP URL とデータベース名を使用します。

"env": { "DATABASE_URL": "http://localhost:8123", "VALV_DATABASE": "analytics" }

MongoDB の場合は、標準の接続文字列を使用します。URL でデータベースが指定されていない場合は、VALV_DATABASE を設定してください。

"env": { "DATABASE_URL": "mongodb://localhost:27017", "VALV_DATABASE": "analytics" }

設定

すべて環境変数で設定します。

変数	説明
DATABASE_URL	接続文字列（必須。代わりに CLI の最初の引数として渡すこともできます）。
VALV_PROVIDER	postgresql | mysql | sqlite | mongodb | clickhouse。省略した場合は URL から推定されます。
VALV_DATABASE	ClickHouse または MongoDB のデータベース名。
VALV_TABLES	カンマ区切りの許可リスト。ここに指定したテーブルのみが公開されます。
VALV_EXCLUDE	カンマ区切りの拒否リスト。許可リストの適用後に適用されます。
VALV_POLICY_FILE	テナントのスコープ設定や非表示フィールドの指定に使うポリシーモジュールのパス（下記参照）。
VALV_CONTEXT	ポリシーが読み取る JSON コンテキスト（例：{"tenant":{"id":"acme"}}）。
VALV_HTTP_PORT	stdio の代わりに、このポートで Streamable HTTP 経由のサービスを提供します。

ポリシーファイル

ポリシーファイルがない場合、すべてのテーブルに対して読み取り専用のアクセスになります。エージェントが参照できるテーブルや列を制限するには、設定済みの valv インスタンスを受け取るモジュールを VALV_POLICY_FILE に指定します。

// valv.policy.cjs
module.exports = (valv) => {
  valv.policy("orders", () => ({
    read:   true,                          // allow reads (or { column: value } to filter rows)
    fields: { deny: ["internal_notes"] },  // hide columns from the agent
  }))
  // Tables without a policy are denied (deny-all).
}

リクエストごとにテナントやユーザー単位で行をスコープ設定する必要がありますか？それは、コードからリクエストごとに実際の ID を渡す、アプリが制御する経路で行います。そうするには @valv/mcp-sdk を使用するか、固定の VALV_CONTEXT を渡し、ここにあるポリシーで読み取ってください。

ライセンス

MIT