Vanna AI MCP服务器
目的：\ 一种模型上下文协议（MCP）服务器，使用Vanna AI为SQL数据库提供自然语言接口。它允许AI助手（如Claude或Gemini）基于简单的英语问题生成和执行SQL查询。
为什么存在：\ 实现无缝的自然语言数据探索。通过将LLM与您的私有SQL数据库桥接（通过SSH隧道），此服务器允许您在不手动编写SQL的情况下“与您的数据聊天”，同时确保您的数据库凭据在远程服务器（如DGX）上的安全。
💰 自由的本地选择
该项目被设计为 完全免费、本地、开源的替代方案 到昂贵的企业数据平台（与中的AI到SQL功能相当 数据砖块 或 雪花).
- 成本： 0美元（不收取每代币费用或每月订阅费）。
- 隐私： 您的数据保留在您的基础设施中。
- 演出 当它在任何东西上运行时，结果都会随着你的硬件而变化。越多 GPU马力 （例如，NVIDIA A100/H100或Apple M系列芯片），您提供的数据洞察力越快、越准确。
特性
- SQL的自然语言： 将用户问题转换为可执行的SQL查询。
- SSH隧道： 从任何环境安全连接到远程数据库（例如DGX上的MySQL）。
- 多个LLM提供商： 支持Ollama（本地）、LM Studio（本地），Claude（Anthropic）、Gemini（谷歌）和ChatGPT（OpenAI）。
- 矢量存储培训： 使用ChromaDB记住数据库模式和常见查询，以提高准确性。
- 苏格兰和南方能源公司运输： 专为使用服务器发送事件的高性能容器化部署而构建。
\[！警告\] Olama业绩说明： 与当地Ollama一起跑步(LLM_TYPE=ollama)可以是 缓慢且可能不可靠 这取决于你的硬件。如果您遇到超时或不一致的SQL生成，请考虑使用Gemini或OpenAI等云提供商进行生产使用。设置
1.先决条件
- Python 3.11+
- 正在运行的SQL数据库（或SSH访问数据库）。
- 本地AI： 下载Ollama 用于局部推理。
🍎 Mac用户？
跟随 Mac和本地Ollama安装指南（50步） 了解从零到正在运行的服务器的详细演练。
2.安装
git clone https://github.com/lilgreml1n/vanna-mcp
cd vanna-mcp
uv pip install -e .3.配置
创建一个 .env 根目录中的文件：
# --- LLM CONFIG ---
LLM_TYPE=ollama # choices: ollama, lmstudio, claude, gemini, openai
# OLLAMA CONFIG
OLLAMA_MODEL=codellama
# CLAUDE CONFIG
# ANTHROPIC_API_KEY=your_key_here
# CLAUDE_MODEL=claude-3-5-sonnet-20241022
# GEMINI CONFIG
# GEMINI_API_KEY=your_key_here
# GEMINI_MODEL=gemini-1.5-flash
# OPENAI CONFIG
# OPENAI_API_KEY=your_key_here
# OPENAI_MODEL=gpt-4o提供的工具
ask_database：将问题转换为SQL，并可选择执行它。train_vanna：提供DDL或示例SQL来“教导”您的模式模型。get_tables：列出所有可用表。get_schema：获取特定表的列详细信息。execute_sql：运行手动SQL进行验证。
🧪 快速开始使用示例数据
如果您还没有准备好数据库，可以设置一个示例库存数据库进行测试：
- 创建示例数据库：
在MySQL环境中运行附带的安装脚本：
mysql -u root -p < setup_test_db.sql这创建了一个 inventory_db 带着一个 inventory 表格和20个样品。
📋 样本数据中有什么？
该脚本预加载了各种项目，因此您可以立即进行测试：
- 耐克 B-12行李箱中的Air Max 90（男式10.5，黑/白）。
- 巴塔哥尼亚 A-10箱子里有更好的毛衣（中性款L）。
- 阿迪达斯 Ultraboost 21（女子8号）在B-05垃圾箱。
- 李维斯牛仔裤 C-22箱子里有501条原装牛仔裤（32x34）。
- …以及来自不同品牌的16件更逼真的物品！
- 配置
.env:
指出你的 .env 到这个新数据库：
MYSQL_DATABASE=inventory_db
# ... rest of your MySQL credentials ...💻 硬件测试和验证
该项目已在两个主要环境中经过严格测试，以确保从本地开发到生产级AI计算的可扩展性。
1.高性能AI服务器（DGX级）
- CPU： 20核高性能处理器（Cortex-X925/A725架构）
- 猛撞： 128GB LPDDR5x
- 储存： 4TB NVMe Gen4固态硬盘
- 用途： Vanna AI、MySQL数据库和大型矢量存储的主要主机。以亚秒级的响应时间运行多个并发LLM流（Ollama/Docker）。
2.本地开发（MacBook Air）
- 型号： MacBook Air（M1/M2/M3硅）
- 猛撞： 16GB统一内存（建议本地Ollama使用最低容量）
- 用途： 用于客户端MCP代理和小型LLM模型（Llama3-8B）的本地测试。
- 注： 由于集成了GPU/NPU加速，Apple Silicon的性能非常出色。
🚀 零到人工智能设置（适用于人工智能代理）
我们的目标： 您应该能够将任何AI（Claude、Gemini或Copilot）指向此自述文件，并在几分钟内运行。
1.适用于克劳德台式机（Mac）
将此添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"vanna-ai": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network=host", "-v", "vanna_chroma_data:/app/chroma_data", "--env-file", "/path/to/your/vanna-mcp/.env", "vanna-mcp-server"]
}
}
}2.适用于Gemini CLI（本地）
在你的 gemini-cli-mcp 项目，更新 main_mcp.py 指向此服务器：
MCP_SERVERS = {
"vanna-ai": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network=host", "vanna-mcp-server"]
}
}3.GitHub副本/VS代码
- 安装 MCP扩展 在VS代码中。
- 使用以下命令添加Vanna MCP服务器：
docker run -i --rm --network=host vanna-mcp-server. - 你现在可以问Copilot：
@mcp /ask_database "Show me all items in bin B-12"
💡 测试你的AI
连接后，尝试以下提示：
- “我们总共有多少件耐克商品？”
- “我们最近卖的最贵的东西是什么？”（使用join-on
ebay_orders) - “列出所有未售出的阿迪达斯商品。”
与SparkForge集成
此服务器通常部署在DGX或高性能服务器上，作为 SparkForge 生态系统。它充当其他MCP代理的“大脑”，如 inventory-mcp.