Vanna AI MCP Server

MCP (Model Context Protocol) server that enables AI assistants to query databases using natural language via Vanna AI.

Features

🗣️ Natural Language SQL: Ask questions in plain English, get SQL queries automatically
🔐 Secure SSH Tunneling: Connects to remote databases via SSH with key or password auth
🤖 AI Training: Train Vanna on your database schema and sample queries
🔌 MCP Compatible: Works with Claude Desktop, Gemini CLI, and other MCP clients
📊 ChromaDB Vector Store: Persistent storage for trained SQL patterns

Quick Start

Using Docker (Recommended)

# Create .env file (see .env.sample)
cp .env.sample .env
# Edit .env with your credentials

# Run with Docker Compose
docker-compose up -d

Server runs on http://localhost:8000

Local Installation

# Install with uv
uv pip install vanna chromadb sshtunnel python-dotenv mcp starlette uvicorn

# Run the server
uv run python main.py

Configuration

Create a .env file with these variables:

# SSH Tunnel Configuration
SSH_HOST=your-server.com
SSH_PORT=22
SSH_USERNAME=your-user
SSH_PASSWORD=your-password          # OR use key-based auth
SSH_KEY_PATH=/path/to/private/key   # Optional
SSH_KEY_PASSPHRASE=key-passphrase   # Optional

# MySQL Database (on remote server)
MYSQL_REMOTE_HOST=localhost  # Usually localhost when using tunnel
MYSQL_REMOTE_PORT=3306
MYSQL_DATABASE=your_database
MYSQL_USER=db_user
MYSQL_PASSWORD=db_password

# Vanna AI
VANNA_MODEL=chinook            # Your model name
VANNA_API_KEY=your-api-key     # Get from vanna.ai

Available MCP Tools

generate_sql - Generate SQL from natural language question
run_sql - Execute SQL query and return results
train_question_sql - Train Vanna with example question/SQL pairs
train_ddl - Train Vanna on database schema (DDL statements)
get_training_data - View all trained examples

Usage Examples

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vanna-ai": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/fastmcp/main.py"]
    }
  }
}

Example Queries

You: Show me the top 5 customers by total sales
Claude: [generates and runs SQL query]

You: What tables are in the database?
Claude: [calls get_training_data to see schema]

You: Train this: "show active users" -> SELECT * FROM users WHERE active=1
Claude: [calls train_question_sql]

Project Structure

fastmcp/
├── main.py              # MCP server with Vanna integration
├── docker-compose.yml   # Docker deployment
├── Dockerfile
├── pyproject.toml       # uv dependencies
├── .env.sample          # Configuration template
└── chroma_data/         # ChromaDB vector storage (persistent)

Tech Stack

Vanna AI: Natural language to SQL conversion
ChromaDB: Vector database for training data storage
MCP: Model Context Protocol for AI tool integration
SSH Tunnel: Secure remote database access
FastAPI/Starlette: HTTP server framework

Security Notes

Never commit .env file to version control
Use SSH key authentication when possible
Database credentials are transmitted only through SSH tunnel
ChromaDB data is persisted in chroma_data/ directory

License

Personal use. Database access and credentials remain private.

vanna-mcp