MCP Bigquery

mcp大查询

通过模型上下文协议进行安全的BigQuery探索

文档 | 快速开始 | 工具 | 例子

______________________________________________________________________

📌 这是什么？

mcp大查询 是一个MCP（模型上下文协议）服务器，它使像克劳德这样的人工智能助手能够 安全地 与谷歌BigQuery互动。

🎯 主要特点

graph LR
    A[AI Assistant] -->|MCP Protocol| B[mcp-bigquery]
    B -->|Dry-run Only| C[BigQuery API]
    B -.->|❌ Never Executes| D[Actual Query Execution]

• 🛡️ 100%安全：所有操作都只是模拟运行（从不执行查询）
• 💰 成本透明度：在运行任何查询之前查看成本
• 🔍 完整分析：分析依赖关系并验证SQL语法
• 📊 架构资源管理器：轻松浏览数据集、表和列

⚡ 为什么使用mcp-bigquery？

🚀 快速入门（4分钟）

步骤1：安装（1分钟）

pip install mcp-bigquery

第二步：使用Google Cloud进行身份验证（2分钟）

# For personal accounts
gcloud auth application-default login

# For service accounts
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

步骤3：配置Claude桌面（1分钟）

打开您的Claude桌面配置：

• 苹果电脑: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"  // ← Replace with your project ID
      }
    }
  }
}

第四步：测试一下！

重新启动Claude Desktop并尝试以下问题：

"What datasets are available in my BigQuery project?"
"Can you estimate the cost of: SELECT * FROM dataset.table"
"Show me the schema for the users table"

🛠️ 可用工具

📝 SQL验证和分析

🔍 架构发现

💡 真实世界的例子

示例1：运行前检查成本

# Before running an expensive query...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"

# First, check the cost
result = bq_dry_run_sql(sql=query)
print(f"Estimated cost: ${result['usdEstimate']}")
print(f"Data processed: {result['totalBytesProcessed'] / 1e9:.2f} GB")

# Output:
# Estimated cost: $12.50
# Data processed: 2500.00 GB

示例2：了解表结构

# Check table schema
result = bq_describe_table(
    dataset_id="your_dataset",
    table_id="users"
)

# Output:
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
#     ├── name (STRING)
#     └── age (INTEGER)

示例3：跟踪数据依赖关系

# Understand query dependencies
query = """
WITH user_stats AS (
  SELECT user_id, COUNT(*) as order_count
  FROM orders
  GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""

result = bq_extract_dependencies(sql=query)

# Output:
# Tables: ['orders', 'users']
# Columns: ['user_id', 'name', 'id']
# Dependency Graph:
#   orders → user_stats → final_result
#   users → final_result

🎨 运作原理

Your Code ← → Claude/AI Assistant
                   ↓
            MCP Protocol
                   ↓
            mcp-bigquery
                   ↓
         BigQuery API (Dry-run)
                   ↓
             BigQuery
      (Never executes actual queries)

⚙️ 配置

环境变量

export BQ_PROJECT="my-project"        # GCP Project ID (required)
export BQ_LOCATION="asia-northeast1"  # Region (optional)
export SAFE_PRICE_PER_TIB="5.0"      # Price per TiB (default: $5)
export LOG_LEVEL="INFO"              # Optional log level override

完整的Claude桌面配置

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "my-production-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "6.0",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

🔧 故障排除

常见问题及解决方案

❌ 认证错误

Error: Could not automatically determine credentials

解决方案：

gcloud auth application-default login

❌ 权限错误

Error: User does not have bigquery.tables.get permission

解决方案： 授予BigQuery Data Viewer角色

gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="user:your-email@example.com" \
  --role="roles/bigquery.dataViewer"

❌ 项目未设置

Error: Project ID is required

解决方案： 集 BQ_PROJECT 在你的配置中

调试模式

如果问题仍然存在，请启用调试模式：

{
  "env": {
    "LOG_LEVEL": "INFO",
    "BQ_PROJECT": "your-project"
  }
}

📚 了解更多

入门指南

• 安装指南
• 使用指南

对于开发者

• 地方发展
• 贡献指南

🚦 项目状态

🤝 贡献

欢迎拉取请求！查看我们的 贡献指南.

# Setup development environment
git clone https://github.com/caron14/mcp-bigquery.git
cd mcp-bigquery
pip install -e ".[dev]"

# Run tests
pytest tests/

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

🙏 致谢

• Google BigQuery团队提供卓越的API
• MCP协议的拟人化
• 所有贡献者和用户

______________________________________________________________________

专为安全的BigQuery探索而构建 🛡️

报告Bug · 请求功能 · 讨论