Vertica Mcp

Vertica MCP 服务

将 MCP 客户端连接到 Vertica，以查询数据、检查表结构，并探索视图和投影。**默认只读。**首次使用时建立连接，并在空闲期间复用。服务通过 stdio 通信。

现有客户端配置、环境变量名称、工具名称和 CLI 别名仍可使用。请参阅升级说明，了解有意修复的 Bug 和安全限制。

快速开始

需要 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	列、可空性、约束、所有权

传递给目录工具的名称必须完全匹配，包括大小写和空格。不要用 SQL 引号将其括起来。省略架构时，将使用 VERTICA_DEFAULT_SCHEMA（public）。 所有目录筛选条件都使用绑定参数。

参数化查询调用：

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

驱动程序使用 ? 占位符。请按顺序提供值；不要将值插入 SQL。参数表示值，而非表或列标识符。

JavaScript 安全范围内的 INTEGER 值会以数字表示；较大的 64 位整数会以十进制字符串表示，以保留精度。字段元数据包含实际的 Vertica 类型名称和 ID，以及线缆格式。

结果会在 content 中保留原始 JSON 文本，并同时提供对应的 structuredContent。数据库和策略错误会设置 MCP isError: true 和 success: false。发现及帮助/版本命令不会连接 Vertica。

输入架构会拒绝未知参数名称，包括不受支持的分页或行数限制选项。请仅使用已声明的参数。输出架构会区分成功和失败，并说明行、字段、元数据、计数和截断情况。 execute_query.rowCount 统计返回的结果行数，而非写入操作影响的行数；list_indexes.indexCount 统计投影-列条目数，而非不同投影的数量。

目录工具会针对其固定查询声明只读行为。任意 SQL 工具都使用保守注释：函数可能产生副作用，因此服务不会声称其具有纯函数性、幂等性或封闭交互世界。这不会禁用默认的只读策略。它们的 _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 和尾随分号的查询。即使 maxRows 小于 batchSize，也会遵守 maxRows；额外读取一行以检测截断。

• batchSize：1–10,000；默认值为 1,000。
• maxRows：1–1,000,000。若省略，则默认为 batchSize × 100，上限为 1,000,000。
• truncated 和顶层的 hasMore：存在更多行时为 true。
• batchCount 和 totalRows：实际返回的批次数和行数。

此工具返回一个 MCP 响应。它不会传输增量消息流，也不提供续传游标。行会在内存中 物化；限制按行数而非字节数计算。请使用较小的限制，并仅选择所需的列。 使用 ORDER BY 可确保排序可复现。execute_query 执行 SQL 时仍不设上限；查询大型结果时请添加 LIMIT。

list_indexes 保留其旧名称和输出字段。Vertica 使用投影而非传统索引；isUnique 反映目录中的 is_key_constraint_projection 标志，并非独立的唯一性证明。 list_views.definition 保留其 200 字符的预览；fullDefinition 提供完整 SQL。

配置

必需：VERTICA_HOST、VERTICA_DATABASE 和 VERTICA_USER。 VERTICA_PASSWORD 为可选项（例如，数据库使用信任身份验证时）。

变量	默认值	含义
VERTICA_PORT	5433	TCP 端口，1–65535
VERTICA_READONLY_MODE	true	只读查询策略和事务
VERTICA_QUERY_TIMEOUT	60000	连接和查询超时时间，单位为 ms；1000–300000
VERTICA_IDLE_TIMEOUT	3600000	空闲断开连接时间，单位为 ms；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 语句。它会拒绝多条语句、包含写操作的 CTE、SELECT INTO，以及对写操作执行的 EXPLAIN。支持处理开头的注释、带引号的值和标识符，以及末尾的分号。每条查询都在 Vertica 只读事务中运行，并在取得结果后回滚。回滚失败会使客户端失效。

语句检查有意采取保守策略。它可能会拒绝一些不常见但有效的 SQL，包括未加引号的变更关键字和有歧义的反斜杠转义。请使用带引号的标识符和绑定值。它不是完整的 SQL 解析器，也不是针对任意函数的沙箱。Vertica 只读事务无法阻止所有可能的函数副作用或磁盘写入。请使用仅具备最低权限的专用账户，并授予 SELECT 和架构 USAGE 权限，同时避免使用有特权的管理函数或用户定义函数。请将查询结果视为不可信数据。

要显式启用写操作：

VERTICA_READONLY_MODE=false

此时，execute_query 每次调用可接受一条写语句。stream_query 仍仅支持 SELECT/WITH。发生错误或超时时，绝不会自动重放 SQL。取消操作或超时会关闭受影响的连接，以停止驱动程序工作；写操作中断后，其执行结果可能无法确定。重试写操作前，请检查数据库状态。

升级

npm 包名称、两个二进制别名、标志、环境变量、六个工具、参数名称和 JSON 文本字段均保持不变。现在需要 Node 20+。有意进行的更正列于 CHANGELOG.md：

• 对所有布尔设置而言，字符串 false 现在都表示 false；拼写错误会被拒绝。
• TLS 设置现在会配置驱动程序实际使用的 TLS 模式。
• SQL 策略修复了前缀检查绕过问题；脚本必须分开调用。
• 工具调用失败时，现在会设置 MCP 错误标志。
• 批量查询只运行一次，遵循限制，并明确报告截断情况。

此版本使用当前稳定版 MCP TypeScript SDK v2，并通过 SDK 的 serveStdio 入口显式提供 2026-07-28 协议。使用 initialize 握手的旧版客户端也可以正常工作。最低 Node 版本现为 20；开发时请使用 Node 24 LTS。现有环境文件和只读默认设置仍受支持。不会引入 HTTP 传输或网络侦听器。

发布与本地验证

有关版本管理、GitHub 草稿发布、带校验和的制品，以及需单独授权并附带 provenance 的 npm 发布，请参阅发布流程。合并前，请使用专用的 Mac 只读交接流程，并搭配通过 CI 的制品和现有环境文件。在实际本地验证期间，切勿运行聚合、模拟、拒绝或写入路径测试套件。

开发与故障排除

设置、检查、架构、包验证和选择加入的数据库集成测试，请参阅 CONTRIBUTING.md。

• 连接失败：检查主机、端口、凭据、网络连通性和 TLS 信任设置。使用相同账户通过 vsql 测试。
• 权限失败：仅授予所需的架构/表访问权限。目录发现只会报告配置账户可见的对象。
• 超时：优化查询，或在允许范围内调高 VERTICA_QUERY_TIMEOUT。超时的客户端会被关闭，后续调用将打开新连接。
• 输出过大：添加 LIMIT，或为 stream_query.maxRows 设置较小的值；可能会在达到行数上限前触及客户端消息大小限制。
• Stdio 失败：标准输出专供 MCP 使用。服务器诊断信息会发送到标准错误。请配置绝对环境文件路径，并检查客户端的服务器日志。

许可证与致谢

MIT。原始项目借鉴了 @nolleh 开发的 mcp-vertica。