Vertica MCP Server
A Model Context Protocol (MCP) server that provides comprehensive Vertica Database integration capabilities for AI assistants and agents.
Features
- Query Execution: Execute SQL queries with safety controls (SELECT, DESCRIBE, EXPLAIN only)
- Schema Inspection: Browse database tables, views, and Vertica-specific projections
- Database Documentation: Generate comprehensive database documentation
- Query Analysis: Analyze query performance with execution plans
- Data Export: Export query results in JSON and CSV formats
- Vertica-Specific: Support for projections, cluster status, and columnar storage features
Installation
Prerequisites
- Python 3.11 or higher
- Access to a Vertica database
uv package manager
Install from Source
git clone <repository-url>
cd vertica-mcp-server
uv sync
Install as Package
uv add vertica-mcp-server
Quick Start
- Set up environment variables:
export DB_CONNECTION_STRING="vertica://username:password@hostname:5433/database"
- Start the MCP server:
- Use with AI assistants that support MCP (like Claude Desktop or VS Code extensions)
Configuration
URL Format (recommended):
vertica://username:password@hostname:port/database
Simple Format:
When using simple format, set these environment variables:
VERTICA_USER: Database usernameVERTICA_PASSWORD: Database password
Environment Variables
| Variable | Description | Default |
|---|
DB_CONNECTION_STRING | Database connection string | Required |
VERTICA_USER | Database username (for simple format) | dbadmin |
VERTICA_PASSWORD | Database password (for simple format) | Empty |
QUERY_LIMIT_SIZE | Maximum rows returned per query | 100 |
MAX_ROWS_EXPORT | Maximum rows for export operations | 10000 |
DEBUG | Enable debug logging | false |
TABLE_WHITE_LIST | Comma-separated list of allowed tables | All tables |
COLUMN_WHITE_LIST | Comma-separated list of allowed columns | All columns |
Docker Development
A Docker setup is provided for testing with Vertica Community Edition:
cd docker-example
docker-compose up -d
See docker-example/README.md for detailed instructions.
The MCP server provides these tools for AI assistants:
- execute_query: Execute SQL queries (SELECT, DESCRIBE, EXPLAIN only)
- describe_table: Get detailed table column information
- list_tables: List all tables with metadata
- list_views: List all database views
- list_projections: List Vertica projections (unique to Vertica)
- explain_query: Get query execution plans
- generate_sample_queries: Generate example queries for tables
- export_query_results: Export query results as JSON or CSV
Vertica-Specific Features
This server includes Vertica-specific functionality:
- Projections: List and inspect Vertica projections
- Columnar Storage: Handle Vertica's columnar data types
- Query Optimization: Vertica-specific query execution plans
- Data Types: Support for Vertica data types (UUID, ARRAY, etc.)
Safety Features
- Query Restriction: Only SELECT, DESCRIBE, and EXPLAIN statements allowed
- Row Limiting: Automatic LIMIT clause added to prevent large result sets
- SQL Injection Protection: Basic protection against malicious queries
- Whitelisting: Optional table and column whitelisting
Development
Running Tests
# Run all tests
uv run pytest
# Run unit tests only
uv run pytest -m unit
# Run integration tests only (requires running Vertica instance)
uv run pytest -m integration
# Run tests with coverage
uv run pytest --cov=src/vertica_mcp_server
Code Quality
# Format code
uv run black src/ tests/
# Sort imports
uv run isort src/ tests/
# Type checking
uv run mypy src/
# Lint code
uv run flake8 src/ tests/
Project Structure
vertica-mcp-server/
src/vertica_mcp_server/
__init__.py
server.py # Main server implementation
py.typed
tests/ # Test suite
docker-example/ # Docker setup for testing
docs/ # Documentation
pyproject.toml # Project configuration
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run the test suite
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Changelog
0.1.0
- Initial release
- Core MCP server functionality
- Vertica database integration
- Query execution and schema inspection
- Docker development environment
- Comprehensive test suite