使用说明

🔷 BigQuery MCP服务器

一个生产就绪的模型上下文协议服务器，为AI代理提供经过身份验证的、速率受限的Google BigQuery访问权限。

概述

AI代理需要对BigQuery进行结构化、安全的访问，而不会暴露原始凭据或允许无限制的查询执行。这 BigQuery MCP服务器 通过将Google BigQuery封装在具有OAuth风格身份验证、每客户端速率限制和结构化日志记录的安全模型上下文协议接口后面，解决了这个问题。

专为将LLM代理连接到实时数据的AI工程师而设计。

功能摘要

功能	描述	状态
OAuth风格的身份验证	`client_id` + `client_secret` → 会话令牌（1小时到期）	已启用
每客户端速率限制	每客户端每60秒30个请求	已启用
`bq.run_query`	对BigQuery执行任意SQL	可用
`bq.list_tables`	列出数据集中包含元数据的表	可用
`bq.get_table_profile`	行数、字节数、模式、示例行、分区/集群信息	可用
结构化日志	记录所有请求、失败和警告	已启用
安全凭据加载	通过env-var加载凭据，从不硬编码	强制
会话生命周期管理	自动令牌到期和验证	强制执行

快速设置

# 1. Clone the repository
git clone https://github.com/your-org/bigquery-mcp-server.git
cd bigquery-mcp-server

# 2. Install dependencies
pip install -r requirements.txt

# 3. Place your GCP service account key in the project root
#    WARNING: Never commit this file — it is excluded via .gitignore
mv ~/Downloads/your-service-account-key.json ./bigquery-credentials.json

# 4. Set environment variables
export GOOGLE_APPLICATION_CREDENTIALS=./bigquery-credentials.json
export CLIENTS_JSON='{"your_client_id": "your_client_secret"}'

# 5. Start the server
python main.py

所需的环境变量：

变量	描述
`GOOGLE_APPLICATION_CREDENTIALS`	GCP服务帐户JSON密钥文件的路径
`CLIENTS_JSON`	已注册客户端凭据的JSON字符串（例如。 `{"client_id":"secret"}`)

安全通知： bigquery-credentials.json 决不能致力于版本控制。确保它列在 .gitignore。以与生产密码相同的方式对待服务帐户密钥。

特色深潜

身份验证——OAuth风格的会话令牌

它的作用： 客户端通过发送 client_id 和 client_secret服务器根据已注册的客户端列表（从以下位置加载）验证凭据 CLIENTS_JSON)并且，如果有效，则发出有时限的会话令牌（1小时到期）。

为什么重要： 原始GCP凭据永远不会离开服务器环境。每个AI代理或工具调用程序都使用一个作用域的过期会话令牌而不是一个长期的秘密进行操作。这限制了令牌泄漏时的爆炸半径，并强制执行显式的重新身份验证。

请求：

{
  "method": "auth/authenticate",
  "params": {
    "client_id": "demo_client_id_123",
    "client_secret": "demo_secret_xyz789"
  }
}

答复：

{
  "result": {
    "session_token": "abcdef123456...",
    "expires_at": "2025-01-01T12:00:00Z",
    "client_id": "demo_client_id_123"
  }
}

速率限制——每客户端请求限制

它的作用： 每个经过身份验证的客户端每60秒窗口限制为30个请求。超过此限制的请求会收到错误响应，而不会触发BigQuery。

为什么重要： BigQuery按扫描的字节计费。无边界的代理循环或失控的工具调用可能会在几秒钟内产生巨大的成本。每个客户的费率限制提供了一个硬护栏，保护您的GCP预算和您的服务对其他客户的可用性。

`bq.run_query` --执行SQL

它的作用： 对BigQuery项目执行任意SQL查询，并将结果作为结构化JSON返回。

为什么重要： 为AI代理提供基于SQL的数据检索的全部功能，同时将执行保持在受控、经过身份验证和速率受限的环境中。

请求：

{
  "method": "tools/call",
  "params": {
    "name": "bq.run_query",
    "arguments": {
      "sql": "SELECT user_id, revenue FROM `project.dataset.table` LIMIT 10"
    },
    "session_token": "<your_session_token>"
  }
}

`bq.list_tables` --数据集探索

它的作用： 列出指定BigQuery数据集中的所有表，返回表名和可用元数据。

为什么重要： 在AI代理可以查询数据之前，它需要发现存在哪些表。该工具支持动态数据集探索，而不需要代理事先了解模式。

请求：

{
  "method": "tools/call",
  "params": {
    "name": "bq.list_tables",
    "arguments": { "dataset_id": "your_dataset" },
    "session_token": "<your_session_token>"
  }
}

`bq.get_table_profile` --表统计和模式

它的作用： 返回表的全面配置文件，包括：行数、以字节为单位的存储大小、完整架构、示例行、分区详细信息、聚类字段和上次修改的时间戳。

为什么重要： 人工智能代理在构建查询之前从理解数据的形状和规模中受益。表配置文件可以减少产生幻觉的列名，防止对大型数据集进行全表扫描，并使代理能够编写更精确、更经济高效的SQL。

请求：

{
  "method": "tools/call",
  "params": {
    "name": "bq.get_table_profile",
    "arguments": {
      "dataset_id": "your_dataset",
      "table_id": "your_table"
    },
    "session_token": "<your_session_token>"
  }
}

建筑

  ┌──────────────────────────────────────┐
  │           MCP Client                  │
  │   (LLM Agent / AI Tool / App)        │
  └──────────────────┬───────────────────┘
                     │
                     │  Step 1: client_id + client_secret
                     ▼
  ┌──────────────────────────────────────┐
  │        Authentication Manager        │
  │  - Validates client credentials      │
  │  - Issues session token (1hr expiry) │
  │  - Enforces session lifecycle        │
  └──────────────────┬───────────────────┘
                     │
                     │  Step 2: session_token returned to client
                     │
                     │  Step 3: Tool call + session_token
                     ▼
  ┌──────────────────────────────────────┐
  │         BigQuery MCP Server          │
  │  ────────────────────────────────    │
  │  Security Layers:                    │
  │    - Token validation                │
  │    - Rate limiter (30 req / 60s)     │
  │    - Structured request logging      │
  │  ────────────────────────────────    │
  │  MCP Tools:                          │
  │    - bq.run_query                    │
  │    - bq.list_tables                  │
  │    - bq.get_table_profile            │
  └──────────────────┬───────────────────┘
                     │
                     │  Step 4: Authenticated BigQuery API call
                     ▼
  ┌──────────────────────────────────────┐
  │          Google BigQuery             │
  │   Datasets, tables, query results    │
  └──────────────────────────────────────┘
                     │
                     │  Step 5: Result returned as JSON
                     ▼
             Back to MCP Client

文件夹结构

bigquery-mcp-server/
├── bigquery_server.py    # Main MCP server — auth, tools, rate limiting
├── config.py             # Project config & registered clients (loads CLIENTS_JSON)
├── main.py               # Entry point — starts the MCP server via uvicorn
├── requirements.txt      # Python dependencies (fastmcp, google-cloud-bigquery, etc.)
├── pyproject.toml        # Project metadata and build configuration
└── README.md             # This file

# bigquery-credentials.json — GCP service account key
# MUST NOT be committed. Add to .gitignore immediately.
# Load via: export GOOGLE_APPLICATION_CREDENTIALS=./bigquery-credentials.json

需求

Python 3.10+
启用BigQuery API的谷歌云项目
具有以下IAM角色的服务帐户：
- BigQuery Data Editor
- BigQuery Job User
服务帐户密钥文件（JSON）——存储在本地，从不提交

GCP服务帐户设置

Google Cloud Console
  → IAM & Admin
  → Service Accounts
  → Create Service Account
  → Assign roles: BigQuery Data Editor + BigQuery Job User
  → Keys → Add Key → JSON
  → Download and place as: ./bigquery-credentials.json

永不承诺 bigquery-credentials.json 到任何存储库。 添加到 .gitignore 在你第一次承诺之前。如果您不小心提交了凭据，请立即在GCP控制台中旋转密钥。

常见问题

Q1：如何注册新客户？

设置 CLIENTS_JSON 将环境变量映射到JSON对象，将客户端ID映射到secrets：

export CLIENTS_JSON='{"agent_001": "secret_aaa", "agent_002": "secret_bbb"}'

如果 CLIENTS_JSON 如果未设置，服务器将回退到中定义的演示客户端 config.py请勿在生产环境中使用演示客户端。

Q2：会话令牌过期时会发生什么？

1小时后，会话令牌将失效。客户端将在下次工具调用时收到身份验证错误。客户端必须通过调用重新进行身份验证 auth/authenticate 再次与它 client_id 和 client_secret 以获得新令牌。

Q3：存放安全吗 bigquery-credentials.json 在项目目录中？

仅当文件通过以下方式从版本控制中排除时 .gitignore。凭据授予BigQuery对GCP项目的直接访问权限。生产部署的最佳实践是使用机密管理器（例如Google Secret manager、HashiCorp Vault）或通过 GOOGLE_APPLICATION_CREDENTIALS 安全CI/CD管道中的环境变量——永远不会作为签入文件。

Q4：如何提高高通量客户端的速率限制？

速率限制（30个请求/60秒）在中配置 bigquery_server.py。您可以调整每个客户端或全局的值。请注意，提高限额还会增加您的BigQuery API呼叫量和相关成本-请确保在提高限额之前在GCP中配置了适当的预算警报。

Q5：我可以将此服务器与任何LLM框架一起使用，还是只使用特定的LLM框架？

服务器实现了模型上下文协议（MCP），它与框架无关。任何与MCP兼容的客户端，包括Claude、带有MCP适配器的LangChain代理或自定义工具调用循环，都可以连接到它。服务器通过HTTP上的标准JSON-RPC进行通信，因此也可以直接从任何HTTP客户端调用它进行测试或集成。

技术栈

组件	技术
语言	Python 3.10+
MCP框架	FastMCP(`mcp` 图书馆）
BigQuery客户端	`google-cloud-bigquery`
身份验证	`google-auth`
数据验证	Pydantic
服务器运行时	uvicorn

专为需要从LLM代理安全、可观察、生产级访问BigQuery的AI工程师而设计。

使用说明

🔷 BigQuery MCP服务器

概述

功能摘要

快速设置

特色深潜

身份验证——OAuth风格的会话令牌

速率限制——每客户端请求限制

bq.run_query --执行SQL

bq.list_tables --数据集探索

bq.get_table_profile --表统计和模式

建筑

文件夹结构

需求

GCP服务帐户设置

常见问题

技术栈

相关 MCP

MySQL查询服务器

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

MongoDB 数据库 MCP 服务器

Jupyter笔记本MCP服务器

Claude Code开发工具包

`bq.run_query` --执行SQL

`bq.list_tables` --数据集探索

`bq.get_table_profile` --表统计和模式