Overview

This project provides a lightweight Python MCP (Model Context Protocol) server tailored for Vertica. It exposes a small set of HTTP tools that let downstream applications — including large language models (LLMs) — inspect database schema, sample data, and run controlled read-only queries against a Vertica cluster. The server is intended for situations where you want programmatic, auditable access to schema information without granting full database credentials or direct SQL execution rights to every consumer.

The server is useful for developers building AI integrations, metadata explorers, or data-aware agents that need to understand table structure and produce safe, read-only SQL. It combines schema inspection and configurable access controls (API tokens, optional IP allowlists, TLS) to reduce risk when opening schema-level access to third parties or automated systems.

Features

Schema inspection: list schemas, tables, columns, types and basic constraints
Read-only query execution (configurable, audited)
Sampling helpers to return a few rows for context without full scans
Tool-oriented HTTP API compatible with MCP-style usage (tool discovery + invocation)
Configurable access controls: token-based auth, IP allowlists, optional TLS
Vertica-native connectivity using vertica-python or equivalent driver
Lightweight, easy to run locally, in Docker, or behind a reverse proxy

Installation / Configuration

Install from PyPI or directly from the GitHub repository. Example using pip:

# From GitHub
pip install git+https://github.com/nolleh/mcp-vertica.git

# Or install requirements after cloning
git clone https://github.com/nolleh/mcp-vertica.git
cd mcp-vertica
pip install -r requirements.txt
python -m mcp_vertica.app

Basic environment-driven configuration:

export VERTICA_HOST="vertica.example.local"
export VERTICA_PORT="5433"
export VERTICA_USER="readonly_user"
export VERTICA_PASSWORD="s3cr3t"
export VERTICA_DATABASE="analytics"
export MCP_API_TOKEN="a_long_random_token"
export MCP_BIND="0.0.0.0:8080"

Example YAML configuration (mcp-config.yml):

vertica:
  host: "vertica.example.local"
  port: 5433
  user: "readonly_user"
  password: "s3cr3t"
  database: "analytics"

server:
  bind: "0.0.0.0:8080"
  tls: false

auth:
  token: "a_long_random_token"
  ip_allowlist: ["10.0.0.0/8", "192.168.1.0/24"]
  read_only: true

Run with a config file:

python -m mcp_vertica.app --config mcp-config.yml

Docker example:

docker run -p 8080:8080 \
  -e VERTICA_HOST=vertica.example.local \
  -e VERTICA_USER=readonly_user \
  -e VERTICA_PASSWORD=s3cr3t \
  -e MCP_API_TOKEN=a_long_random_token \
  nolleh/mcp-vertica:latest

Available Tools

The server exposes a small set of introspection and helper tools. Tool names and request formats are JSON-based; example endpoints are shown for illustration.

list_schemas — returns available schema names
list_tables — list tables in a schema with rowcount estimates
describe_table — returns columns, types, nullability, and primary keys
sample_rows — returns N sample rows for a specific table (limit configurable)
execute_read_query — run a read-only SQL query (enforced by server)
health — simple healthcheck endpoint

Example curl invocation (token header required):

curl -X POST "http://localhost:8080/tools/describe_table" \
  -H "Authorization: Bearer a_long_random_token" \
  -H "Content-Type: application/json" \
  -d '{"schema":"public","table":"events"}'

Example JSON response (abbreviated):

{
  "schema": "public",
  "table": "events",
  "columns": [
    {"name":"event_id","type":"INT","nullable":false},
    {"name":"created_at","type":"TIMESTAMP","nullable":false}
  ]
}

Use Cases

LLM-assisted SQL generation: let an LLM ask the MCP server for table schemas and sample rows so it can craft safe, read-only queries.
Metadata-driven UIs: build data catalog UIs that dynamically show columns, types, and small samples without exposing DB credentials.
Integration testing: run schema checks in CI pipelines to validate expected columns/types exist after migrations.
Controlled third-party access: provide partners or analytics teams with programmatic schema inspection while enforcing token auth and IP restrictions.
Auditable query execution: keep a small server-side audit trail of sample and read queries executed via the MCP endpoints.

Security & Best Practices

Always run the server behind TLS in production; use a reverse proxy if the server has no native TLS.
Use long, randomly generated API tokens and rotate them regularly.
Limit the Vertica user to read-only privileges and restrict access to only the schemas/tables required.
Use IP allowlists where possible and enable auditing/logging for all tool invocations.

Resources

Repository: https://github.com/nolleh/mcp-vertica
Vertica Python driver: vertica-python (install via pip)
Example config and sample clients are included in the repository for quick onboarding

This MCP server is intended as a lightweight, auditable bridge between applications (including LLMs) and Vertica schema and data, balancing convenience and security for day-to-day integrations.

Vertica MCP Server Python: Schema Inspection, Access Controls