Bigquery Agent MCP

🤖 使用MCP的BigQuery代理和仪表板

智能代理系统，用于查询BigQuery并自动创建可视化，支持Claude Desktop的MCP协议。

🎯 Nouveau：支持多个LLM！ 该系统现在对LLM模型不可知。选择Gemini、Claude、OpenAI或Ollama。

⚡ 利用 uv 用于超快速可靠的安装！

✨ 功能

• 🔍 代理BigQuery智能 ：自动发现数据集和表
• 📊 代理仪表板 ：自动生成Plotly可视化
• 🔌 支持MCP ：与Claude Desktop和其他MCP客户端兼容
• 🤝 自然互动 ：用自然语言提问
• 🎯 勘探自主 ：代理推理并找到正确的数据
• 🔄 多LLM ：选择您最喜欢的型号（双子座、克劳德、Openai、Ollama）
• ⚡ 安装现代avec uv ：比Pip快10-100倍

📦 快速安装 uv （推荐）

1.紫外线安装器

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

窗户：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.克隆和配置

git clone 
cd agent-py

# Créer le fichier .env
cp .env.example .env
# Éditez .env et ajoutez votre GOOGLE_CLOUD_PROJECT_ID

# Authentification Google Cloud
gcloud auth application-default login

3.这是吹牛！ 🎉

无需手动安装依赖项。 uv 自动处理。

🚀 使用

模式1：带Claude桌面的MCP（推荐）

最低配置-就足够了：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "bigquery-dashboard": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/younessdrissislimani/PycharmProjects/agent-py",
        "run",
        "bigquery-dashboard-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT_ID": "votre-projet-gcp"
      }
    }
  }
}

优点：

• ✅ 无需LLM API密钥（使用Claude）
• ✅ 通过自动安装依赖项 uv
• ✅ 没有虚拟环境管理
• ✅ 简化更新

重新启动Claude桌面，就可以了！

模式2：直接终端使用

带紫外线（推荐）

# Configure ton LLM dans .env
echo 'LLM_PROVIDER=gemini' >> .env
echo 'GEMINI_API_KEY=ta-cle' >> .env

# Lance le script
uv run python main.py

使用经典PIP

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

🔧 方法比较

🛠️ 测试和调试

测试MCP服务器

# Avec uv
uv run bigquery-dashboard-mcp

# Avec Python
python mcp_server.py

MCP检查器（可视化调试）

npx @modelcontextprotocol/inspector uv --directory $(pwd) run bigquery-dashboard-mcp

这将打开一个web界面，以交互方式测试您的工具。

┌─────────────────────────────────────────────────┐
│              Interface Utilisateur              │
├─────────────────┬───────────────────────────────┤
│  Claude Desktop │  Terminal Direct (main.py)    │
│  (utilise       │  (LLM configurable)           │
│   Claude)       │                               │
└────────┬────────┴───────────────────────────────┘
         │                │
         │ MCP            │ Direct
         │                │
┌────────▼────────────────▼───────────────────────┐
│            Orchestration Layer                  │
│  - mcp_server.py (pas de LLM interne)          │
│  - main.py (LLM configurable)                  │
└────────┬────────────────────────────────────────┘
         │
    ┌────┴──────────────────────┐
    │                           │
┌───▼──────────────┐    ┌──────▼──────────────┐
│ BigQuery Agent   │    │ Dashboard Agent     │
│ (LangChain)      │    │ (LangChain)         │
│                  │    │                     │
│ Outils:          │    │ Fonctions:          │
│ - list_datasets  │    │ - Génération code   │
│ - list_tables    │    │ - Visualisation     │
│ - get_schema     │    │   Plotly            │
│ - execute_sql    │    │                     │
└───┬──────────────┘    └──────┬──────────────┘
    │                          │
┌───▼────────────┐      ┌──────▼──────┐
│  Google        │      │   Plotly    │
│  BigQuery      │      │   Express   │
└────────────────┘      └─────────────┘

📦 安装

1.克隆项目

git clone 
cd agent-py

2.创建虚拟环境

python -m venv .venv
source .venv/bin/activate  # Sur Windows: .venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

4.配置环境变量

复制文件 .env.example 朝向 .env 并配置它：

cp .env.example .env

编辑 .env 根据您的用例：

对于MCP（Claude桌面）-最低要求：

GOOGLE_CLOUD_PROJECT_ID="votre-projet-gcp"

直接终端使用-选择您的LLM：

选项1：双子座（谷歌）

GOOGLE_CLOUD_PROJECT_ID="votre-projet-gcp"
LLM_PROVIDER="gemini"
GEMINI_API_KEY="votre-cle-api-gemini"

选项2：克劳德（拟人）

GOOGLE_CLOUD_PROJECT_ID="votre-projet-gcp"
LLM_PROVIDER="claude"
ANTHROPIC_API_KEY="votre-cle-api-claude"

选项3:OpenAI（GPT-4）

GOOGLE_CLOUD_PROJECT_ID="votre-projet-gcp"
LLM_PROVIDER="openai"
OPENAI_API_KEY="votre-cle-api-openai"

选项4：Ollama（当地）

GOOGLE_CLOUD_PROJECT_ID="votre-projet-gcp"
LLM_PROVIDER="ollama"
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama2"

5.认证谷歌云

gcloud auth application-default login

🚀 使用

模式1：带Claude桌面的MCP（推荐）

优点： 不需要LLM API密钥！Claude Desktop使用自己的Claude模型。

1. 仅使用配置Claude桌面 GOOGLE_CLOUD_PROJECT_ID :

{
  "mcpServers": {
    "bigquery-dashboard": {
      "command": "python",
      "args": [
        "/Users/younessdrissislimani/PycharmProjects/agent-py/mcp_server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT_ID": "votre-projet-gcp"
      }
    }
  }
}

1. 重新启动Claude桌面

1. 自然使用Claude：

- “显示BigQuery中每个视频的视图数” - “创建此数据的条形图”

Claude将自动使用MCP工具探索BigQuery！

模式2：直接终端使用

使用您选择的LLM启动交互式主脚本：

python main.py

系统将显示使用的模型：

🤖 Utilisation du modèle: Google Gemini Pro

哦

🤖 Utilisation du modèle: Anthropic Claude 3.5 Sonnet

交互示例：

=== Agent BigQuery Intelligent ===
🤖 Utilisation du modèle: Anthropic Claude 3.5 Sonnet

Posez votre question : donne moi le nombre de vues par vidéo

--- L'agent analyse votre question et explore BigQuery ---
[L'agent liste les datasets...]
[L'agent explore les tables...]
[L'agent examine les schémas...]
[L'agent exécute la requête...]

--- Résultats de la requête ---
   video_id  video_title        views
0  v123      Introduction       15000
1  v124      Tutorial Part 1    8500
2  v125      Demo              12300

Voulez-vous visualiser ces résultats dans un tableau de bord ? (oui/non): oui

--- Création de la Visualisation ---
🤖 Utilisation du modèle: Anthropic Claude 3.5 Sonnet
[Un graphique interactif s'affiche dans votre navigateur]

🔧 模式比较

🛠️ MCP工具可用（Claude桌面）

使用Claude桌面时，Claude可以访问5个工具：

list_bigquery_datasets

列出所有可用的数据集。

list_bigquery_tables

列出数据集中的表。

get_table_schema

获取表的模式。

execute_bigquery_sql

在BigQuery上执行SQL查询。

create_plotly_visualization

从数据创建可视化。

克劳德自动智能地使用它们！

🧪 测试和调试

测试MCP服务器

python mcp_server.py

使用MCP Inspector进行调试

npx @modelcontextprotocol/inspector python mcp_server.py

📁 项目结构

agent-py/
├── main.py                      # Script principal interactif
├── mcp_server.py                # Serveur MCP (agnostique au modèle)
├── requirements.txt             # Dépendances Python
├── .env                         # Variables d'environnement (à créer)
├── .env.example                 # Exemple de configuration
├── MCP_SETUP.md                 # Guide détaillé MCP
├── README.md                    # Ce fichier
└── src/
    ├── llm_config.py            # Configuration dynamique des LLM
    ├── bigquery_agent/
    │   ├── __init__.py
    │   ├── agent.py             # Agent BigQuery (multi-LLM)
    │   └── main.py              # Exemple standalone
    └── dashboard_agent/
        ├── __init__.py
        ├── agent.py             # Agent Dashboard (multi-LLM)
        └── main.py              # Exemple standalone

🔧 使用的技术

• Python 3.12+
• LangChain ：代理编排
• 谷歌云BigQuery ：数据库
• LLM支持 :

- Gemini Pro（谷歌） - 克劳德3.5十四行诗（人物） - GPT-4（OpenAI） - Callama2/Mistral（Ollama-本地）

• Plotly Express ：交互式可视化
• MCP（模型上下文协议） ：与Claude桌面集成

📖 详细文件

• 完整的MCP配置

🤝 兼容性

客户端MCP

• ✅ Claude Desktop（自动使用Claude）
• ✅ Cline/VSCode（可配置）
• ✅ 光标（可配置）
• ✅ Tout客户端MCP

支持LLM（终端模式）

• ✅ 谷歌Gemini Pro
• ✅ 克劳德3.5十四行诗
• ✅ OpenAI GPT-4
• ✅ Ollama（Callama2、Mistral等）

📝 问题示例

• “给我每个视频的浏览量”
• “订单量排名前十的客户是谁？”
• “每月向我展示销售趋势”
• “最畅销产品列表”
• “区域绩效分析”

🚀 多LLM方法的好处

✅ 倒入MCP ：无额外API成本（使用客户的LLM） ✅ 倾倒终端 ：模型选择的完全灵活性 ✅ 供应商锁定 ：随时更改型号 ✅ 成本优化 ：如果需要，在本地使用Ollama ✅ 最佳性能 ：每个模型都有自己的优势

🐛 故障排除

MCP（Claude Desktop）

工具不会出现：

• 检查中的绝对路径 claude_desktop_config.json
• 重新启动Claude桌面
• 检查 GOOGLE_CLOUD_PROJECT_ID 已定义

直接在终端上使用

错误“找不到提供程序”：

# Vérifiez votre fichier .env
cat .env | grep LLM_PROVIDER

错误的“找不到API密钥”：

# Assurez-vous que la clé API correspondante est définie
# Pour Gemini : GEMINI_API_KEY
# Pour Claude : ANTHROPIC_API_KEY
# Pour OpenAI : OPENAI_API_KEY

BigQuery身份验证错误：

gcloud auth application-default login

📄 许可证

麻省理工学院

👤 电影导演

创建于❤️ 为了便于使用AI进行数据分析