valv

Name: valv
Author: valv.sh

本地服务

valv.sh数据库54 周前更新

代码仓库访问官网

关于 valv

@valv/mcp 通过默认只读的 MCP 服务连接编码 Agent 与数据库。它会检查数据库结构并应用表、字段和策略限制，让 Agent 查询获准的数据，而无需接触 SQL。

主要功能

01检查实时数据库结构
02搜索并描述数据库资源
03通过四种工具查询数据
04使用表和字段策略限制访问
05按策略规则筛选行
06通过引导式设置配置客户端

适用场景

01探索获准访问的数据库表
02在不暴露 SQL 的情况下查询数据
03限制 Agent 可见的表
04应用行和字段限制

MCP 相关

向 MCP 客户端提供数据库结构发现和查询工具。通过数据库 URL 建立连接，默认只读，并可用允许列表和策略文件限制访问。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "sh-valv": {
      "command": "npx",
      "args": [
        "-y",
        "@valv/mcp"
      ],
      "env": {
        "DATABASE_URL": "<DATABASE_URL>",
        "VALV_PROVIDER": "<VALV_PROVIDER>",
        "VALV_DATABASE": "<VALV_DATABASE>",
        "VALV_TABLES": "<VALV_TABLES>",
        "VALV_EXCLUDE": "<VALV_EXCLUDE>",
        "VALV_POLICY_FILE": "<VALV_POLICY_FILE>",
        "VALV_CONTEXT": "<VALV_CONTEXT>",
        "VALV_HTTP_PORT": "<VALV_HTTP_PORT>"
      }
    }
  }
}

启动命令npx -y @valv/mcp

需要配置的环境变量

DATABASE_URL密钥Database connection string. PostgreSQL, MySQL, SQLite, CockroachDB, or a ClickHouse HTTP URL.

VALV_PROVIDERDatasource provider: postgresql, mysql, sqlite, or clickhouse. Inferred from DATABASE_URL when omitted.

VALV_DATABASEDatabase name. Required for ClickHouse, whose URL does not carry one.

VALV_TABLESComma-separated allow-list of tables. When set, only these are exposed to the agent.

VALV_EXCLUDEComma-separated deny-list of tables, applied after the allow-list.

VALV_POLICY_FILEPath to a policy module that takes full control of access. Without it, the server is read-only across all tables.

VALV_CONTEXTJSON context object the policy reads, e.g. {"tenant":{"id":"acme"}}.

VALV_HTTP_PORTServe over Streamable HTTP on this port instead of stdio.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@valv/mcp0.6.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@valv/mcp

指定数据库 URL，即可让 Agent 安全地查询。无需 SQL，无需代码。

这是一个基于 valv 构建的零配置 MCP 服务。提供连接字符串后，它会检查实时数据库架构，提供四种工具（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 技能的选项，用于教会 Agent 如何查询 valv 并将结果转换为交互式图表报告 HTML 文件。该技能可作为 Claude Code（.claude/skills）、Codex（.agents/skills）或 Cursor（.cursor/skills）技能，安装到项目级或全局范围。最后，它还可以将快速启动提示词复制到剪贴板——粘贴到你的 Agent 中，即可探索数据库架构（为后续查询生成 .valv/notes.md），并生成一份交互式 valv-map.html 数据库概览。

手动设置

将其添加到你的 .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`	在此端口通过 Streamable HTTP 提供服务，而非使用 stdio。

策略文件

未指定策略文件时，所有数据表均为只读访问。若要限制 Agent 可见的内容——包括哪些数据表、哪些列——请将 VALV_POLICY_FILE 指向一个接收已配置 valv 实例的模块：

// 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).
}

需要按租户 / 用户对每个请求进行行级范围限定？这应在由应用控制的路径中完成，由你的代码为每个请求提供真实身份——请使用 @valv/mcp-sdk（或传入固定的 VALV_CONTEXT，并在此处的策略中读取）。