Bigquery Mcp

🗂️ BigQuery MCP 服务

实用的 MCP 服务，可供大模型浏览 BigQuery 数据集和表。专为包含大量数据集和表的大型项目设计，在保持快速、安全的同时，尽量减少大模型上下文占用。

• 默认保持精简：仅列出数据集和表的名称；只有在需要时才获取详细信息
• 浏览大型项目：按名称筛选，按需获取详细元数据和架构
• 快速了解表信息：可选查看架构、列描述和填充率，帮助 Agent 快速判断相关性
• 安全运行：只读查询执行，并设有防护措施（仅允许 SELECT/WITH，剥除注释）
• 支持向量搜索：使用 BigQuery 作为向量存储。完整设置说明请参阅 向量搜索 部分。

快速开始

**前提条件：**Python 3.10+ 和 uv 包管理器

🚀 快速设置

选项 1：直接从 PyPI 安装（推荐）

# 1. Authenticate
gcloud auth application-default login

# 2. Run server
uvx bigquery-mcp --project YOUR_PROJECT --location US

选项 2：克隆到本地（开发环境设置）

# 1. Clone and setup
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp

# 2. Configure environment
cp .env.example .env
# Edit .env with your project and location

# 3. Run or inspect
make run      # Start server
make inspect  # Open MCP inspector

🔧 MCP 客户端配置

选项 1：PyPI 包（推荐） 使用已发布的 PyPI 包进行最简设置：

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "bigquery-mcp",
        "--project", "your-project-id",
        "--location", "US"
     ]
    }
  }
}

选项 2：本地克隆（用于开发）

# Clone first
git clone https://github.com/pvoo/bigquery-mcp.git

{
  "mcpServers": {
    "bigquery": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/bigquery-mcp", "run", "bigquery-mcp"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "BIGQUERY_LOCATION": "US"
      }
    }
  }
}

🧪 测试设置

# Test with MCP inspector
npx @modelcontextprotocol/inspector uvx bigquery-mcp --project YOUR_PROJECT --location US

🔧 配置选项

所有配置均可通过 CLI 参数或环境变量设置。CLI 参数优先级更高。

必需参数

--project YOUR_PROJECT    # Google Cloud project ID
--location US             # BigQuery location (US, EU, etc.)

可选参数

# Dataset Access Control
--datasets dataset1 dataset2    # Restrict to specific datasets (default: all datasets)

# Query & Result Limits
--list-max-results 500          # Max results for basic list operations (default: 500)
--detailed-list-max 25          # Max results for detailed list operations (default: 25)
--max-bytes-billed 109951162777  # Max bytes billed per query job (~USD 0.50/query)

# Table Analysis
--sample-rows 3                 # Sample data rows returned in get_table (default: 3)
--stats-sample-size 500         # Rows sampled for column fill rate calculations (default: 500)

# Authentication
--key-file /path/to/key.json    # Service account key file (default: ADC)

环境变量

所有 CLI 选项都有对应的环境变量：

export GCP_PROJECT_ID=your-project
export BIGQUERY_LOCATION=US
export BIGQUERY_ALLOWED_DATASETS=dataset1,dataset2
export BIGQUERY_LIST_MAX_RESULTS=500
export BIGQUERY_LIST_MAX_RESULTS_DETAILED=25
export BIGQUERY_MAX_BYTES_BILLED=109951162777
export BIGQUERY_SAMPLE_ROWS=3
export BIGQUERY_SAMPLE_ROWS_FOR_STATS=500
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

向量搜索配置

完整设置说明请参阅 向量搜索 部分。

--embedding-model project.dataset.model
--embedding-tables dataset.table1 dataset.table2
--distance-type COSINE

🛠️ 工具概览

此 MCP 服务提供 5 个 BigQuery 工具，针对大模型效率进行了优化：

📊 智能数据集和表发现

• list_datasets - 双模式：基本模式（仅名称）和详细模式（完整元数据）
• list_tables - 可根据上下文浏览表，并可选查看架构详情
• get_table - 全面分析表，包括架构和示例数据

🔍 安全查询执行

• run_query - 仅执行 SELECT/WITH 查询，并提供费用追踪、安全验证，以及默认约 0.50 美元的单次查询计费上限。使用查询中的 LIMIT 子句控制结果大小。

🔮 向量搜索（可选）

• vector_search - 双模式工具：发现嵌入表（不提供 query_text），或执行语义相似度搜索（提供 query_text）

主要功能：

• ✅ 默认保持精简 - 基本模式下可减少 70% 的 token
• ✅ 仅执行安全查询 - 阻止所有写入操作
• ✅ 针对大模型优化 - 返回结构化数据，便于 AI 分析
• ✅ 费用透明 - 显示每次查询处理的字节数
• ✅ 默认限制费用 - 将每个查询作业的费用限制在约 0.50 美元，除非重新配置

🔮 向量搜索（可选）

使用 BigQuery 向量嵌入启用语义相似度搜索。

前提条件：在 BigQuery 中设置嵌入

使用向量搜索前，需要准备嵌入模型和包含嵌入的表：

步骤 1：创建 Vertex AI 连接（一次性设置）

-- In BigQuery console or bq command line
-- This creates a connection to Vertex AI for generating embeddings
CREATE EXTERNAL CONNECTION `your-project.your-region.vertex-ai`
  OPTIONS (
    endpoint = 'https://your-region-aiplatform.googleapis.com',
    type = 'CLOUD_RESOURCE'
  );

步骤 2：创建嵌入模型

CREATE OR REPLACE MODEL `your-project.your_dataset.text_embedding_model`
REMOTE WITH CONNECTION `your-project.your-region.vertex-ai`
OPTIONS (ENDPOINT = 'text-embedding-005');

步骤 3：向表中添加嵌入

-- Add embedding column to existing table
ALTER TABLE `your-project.your_dataset.products`
ADD COLUMN IF NOT EXISTS embedding ARRAY<FLOAT64>;

-- Generate embeddings for your text data
UPDATE `your-project.your_dataset.products` t
SET embedding = (
  SELECT ml_generate_embedding_result
  FROM ML.GENERATE_EMBEDDING(
    MODEL `your-project.your_dataset.text_embedding_model`,
    (SELECT t.name AS content),
    STRUCT(TRUE AS flatten_json_output)
  )
)
WHERE embedding IS NULL;

有关详细设置说明和连接权限，请参阅 BigQuery 文本嵌入文档。

向量搜索的 MCP 配置

设置好嵌入后，配置 MCP 服务：

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "bigquery-mcp",
        "--project", "your-project",
        "--location", "US",
        "--embedding-model", "your-project.your_dataset.text_embedding_model",
        "--embedding-tables", "your_dataset.products", "your_dataset.documents"
      ]
    }
  }
}

配置参考

CLI 参数	环境变量	默认值	描述
--embedding-model	BIGQUERY_EMBEDDING_MODEL	-	必填。 嵌入模型的完整路径（project.dataset.model）。启动时会进行验证。
--embedding-tables	BIGQUERY_EMBEDDING_TABLES	-	包含嵌入列的表（跳过自动发现）
--vector-column-contains	BIGQUERY_EMBEDDING_COLUMN_CONTAINS	embedding	用于查找嵌入列的模式（列名必须包含此内容）
--distance-type	BIGQUERY_DISTANCE_TYPE	COSINE	距离度量：COSINE、EUCLIDEAN、DOT_PRODUCT
--no-vector-search	BIGQUERY_VECTOR_SEARCH_ENABLED=false	已启用	禁用向量搜索工具

使用示例

发现模式 - 查找包含嵌入的表：

{
  "query_text": ""
}

搜索模式 - 语义相似度搜索：

{
  "query_text": "solenoid valve for water",
  "table_path": "my_dataset.products",
  "top_k": "10",
  "select_columns": "name,description,price"
}

所需权限

角色	用途
roles/bigquery.dataViewer	读取表和模型
roles/bigquery.jobUser	运行 BigQuery 作业
roles/bigquery.metadataViewer	自动发现嵌入表（可选）

🏗️ 开发环境设置

本地开发

# Clone and setup
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp
make install  # Setup environment + pre-commit hooks

# Development workflow
make run      # Start server
make test     # Run test suite
make check    # Lint + format + typecheck
make inspect  # Launch MCP inspector

测试与质量

make test                    # Full test suite
pytest tests/test_safety.py  # SQL safety validation tests
pytest tests/test_server.py  # Core server functionality tests
make check                   # Run all quality checks

🔐 身份验证与权限

身份验证方法：

1. 应用默认凭据（推荐）：gcloud auth application-default login
2. 服务账号密钥：使用 --key-file 或设置 GOOGLE_APPLICATION_CREDENTIALS

所需的 BigQuery 权限：

• bigquery.datasets.get、bigquery.datasets.list
• bigquery.tables.list、bigquery.tables.get
• bigquery.jobs.create、bigquery.data.get

🚨 故障排除

身份验证问题：

# Check current auth
gcloud auth application-default print-access-token

# Re-authenticate
gcloud auth application-default login

# Enable BigQuery API
gcloud services enable bigquery.googleapis.com

MCP 连接问题：

• 确保 MCP 配置中使用绝对路径
• 手动测试服务：make run
• 检查项目和位置环境变量或参数是否已正确设置

性能问题：

• 使用 {"detailed": false} 以获得更快的响应
• 添加搜索筛选条件：{"search": "pattern"}
• 对于大型数据集，降低 max_results

💡 使用示例

📊 SQL 查询示例

-- Query public datasets
SELECT
    EXTRACT(YEAR FROM pickup_datetime) as year,
    COUNT(*) as trips,
    ROUND(AVG(fare_amount), 2) as avg_fare
FROM `bigquery-public-data.new_york_taxi_trips.tlc_yellow_trips_2020`
WHERE pickup_datetime BETWEEN '2020-01-01' AND '2020-12-31'
GROUP BY year
LIMIT 20

🤖 示例：在 Claude Code 子 Agent 中使用

场景： 在 Claude Code 中使用专用的 BigQuery Table Analyst Agent，自动探索数据仓库、分析表之间的关系并提供结构化洞察。使用子 Agent 可以将分析表格时使用的上下文从主线程中移出，并将可执行的洞察返回主 Agent 线程，用于编写 SQL 或进行分析。

设置：

# 1. Clone and configure
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp

# 2. Setup environment
export GCP_PROJECT_ID="your-project-id"
export BIGQUERY_LOCATION="US"
gcloud auth application-default login

# 3. Launch Claude Code
claude-code

使用示例：

💬 You: "I need to understand our sales data structure and find tables related to customer orders"

🤖 Claude: I'll use the BigQuery Table Analyst agent to explore your sales datasets and identify relevant tables with their relationships.

[Agent automatically:]
- Lists all datasets to identify sales-related ones
- Explores table schemas with detailed metadata
- Shows actual sample data from key tables
- Discovers join relationships between tables
- Provides ready-to-use SQL queries

Agent 返回的内容：

• 表架构，包含列说明和类型
• 示例数据，展示实际值（而非占位符）
• 连接关系，包含可运行的 SQL 示例
• 数据质量洞察（空值比例、新鲜度等）
• 可立即执行的 SQL 查询

🤝 参与贡献

欢迎贡献！期待收到你的反馈，以便改进项目。

快速开始：

# Fork on GitHub, then:
git clone https://github.com/yourusername/bigquery-mcp.git
cd bigquery-mcp
make install  # Setup dev environment
make check    # Verify everything works

# Make changes, then:
make test     # Run tests
make check    # Quality checks
# Submit PR!

开发指南：

• 为新功能添加测试
• 更新文档
• 遵循现有代码风格（由 pre-commit 钩子强制执行）
• 确保所有质量检查均通过

发现问题或有功能请求？

• 🐛 错误报告： 提交问题
• 🔧 代码改进： 提交拉取请求
• 📖 文档： 查看 CONTRIBUTING.md

---

🌟 如果这个仓库对你有帮助，请为它点亮星标！