BigQuery MCP 服务器

](https://smithery.ai/protocol/@ergut/mcp-bigquery-server)

这是什么？ 🤔

这是一个服务器，能让您的大型语言模型（如Claude）直接与您的BigQuery数据进行交互！可以将其视为一个友好的翻译器，位于您的AI助手和数据库之间，确保它们能够安全高效地进行对话。

快速示例

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

无需再手动编写SQL查询——只需与您的数据自然对话！

它是如何工作的？ 🛠️（扳手或工具的符号，可译为“扳手”或根据上下文译为“工具”等）

这台服务器使用了模型上下文协议（MCP），该协议就像AI数据库通信的通用翻译器。虽然MCP旨在与任何AI模型配合工作，但目前它仅作为开发者预览版在Claude Desktop中提供。

你所需要做的就是这些：

设置身份验证（见下文）
将您的项目详细信息添加到Claude Desktop的配置文件中
开始自然地与您的BigQuery数据进行对话吧！

它能做什么？ 📊

只需用简单的英语提问即可运行SQL查询
在您的数据集中访问表和物化视图
探索数据集架构，对资源类型（表与视图）进行清晰标注
在安全范围内分析数据（默认查询限制为1GB）
确保您的数据安全（仅读取访问权限）

快速入门 🚀

📦 收到了一个服务账户的JSON文件？ 如果有人与你共享了一个服务账户，请跳至 SETUP_FOR_SHARED_ACCOUNT.md 翻译为中文是：“为共享账户设置指南.md” 以获取逐步操作指南。

先决条件

Node.js 14或更高版本
已启用BigQuery的Google Cloud项目
已安装Google Cloud CLI或服务账户密钥文件
Claude Desktop 或 Claude Code（支持MCP）

选项1：通过Smithery快速安装（推荐）

通过自动方式为Claude Desktop安装BigQuery MCP服务器 Smithery（注：此词并非标准英文词汇，可能是特定领域或虚构作品中的术语，以下为根据字面意思的翻译）可译为“史密斯工坊”或“史密斯制造所”，具体翻译需结合上下文或特定领域背景来确定。如果“Smithery”在某个特定作品或语境中有其特定含义，那么翻译时应考虑该含义在你的终端中运行这个命令：

npx @smithery/cli install @ergut/mcp-bigquery-server --client claude

安装程序将提示您：

您的Google Cloud项目ID
BigQuery 位置（默认为 us-central1）

配置完成后，Smithery 将自动更新您的 Claude Desktop 配置并重启应用程序。

选项2：手动设置

如果您更喜欢手动配置或需要更多控制权：

📱 在多个平台上工作吗？ 见 CROSS_PLATFORM_CONFIG.md 翻译为中文是：跨平台配置文件.md 以下是针对Windows、Mac和Linux的详细配置示例。

使用 Google Cloud 进行身份验证 （选择一种方法）：

- 使用 Google Cloud CLI（非常适合开发）：

     gcloud auth application-default login

- 使用服务帐户（生产环境推荐）：

     # Save your service account key file and use --key-file parameter or .env file
     # Remember to keep your service account key file secure and never commit it to version control

配置凭据 （选择一种方法）：

选项A：使用.env文件（推荐用于本地开发）

- 创建一个 .env 项目根目录下的文件：

     cp .env.example .env

- 编辑 .env 符合您的价值观：

     BIGQUERY_PROJECT_ID=your-project-id
     BIGQUERY_LOCATION=US
     BIGQUERY_KEY_FILE=/path/to/service-account-key.json

- 这个（或“该”） .env 文件已包含在 .gitignore 保护您的凭证安全

选项B：使用命令行参数

- 通过命令行参数直接传递凭据 - 请见以下示例

添加到您的Claude桌面配置中

把它加到你的（清单/列表/计划等）里 claude_desktop_config.json:

> 💡 跨平台小贴士： 对于一个能在Windows、Mac和Linux上无需更改即可正常工作的配置，请使用 npx 使用命令行参数的方式（见下例）。

- 使用 .env 文件（无需参数）：

     {
       "mcpServers": {
         "bigquery": {
           "command": "node",
           "args": [
             "/path/to/mcp-bigquery-server/dist/index.js"
           ]
         }
       }
     }

- 使用命令行参数进行基本配置：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1"
           ]
         }
       }
     }

- 使用服务账户：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json"
           ]
         }
       }
     }

开始聊天吧！

打开Claude桌面版，开始就您的数据提问。

配置选项

服务器支持通过环境变量（.env 文件）或命令行参数进行配置：

环境变量（.env 文件）：

BIGQUERY_PROJECT_ID（必填）您的Google Cloud项目ID
BIGQUERY_LOCATION（可选）BigQuery 位置，默认为“US”
BIGQUERY_KEY_FILE（可选）服务帐户密钥JSON文件的路径

命令行参数：

--project-id（必填）您的 Google Cloud 项目 ID
--location（可选）BigQuery 位置，默认为 'US'
--key-file（可选）服务帐户密钥JSON文件的路径

注：如果同时提供了命令行参数和环境变量，则命令行参数将覆盖环境变量。

使用服务帐户和命令行参数的示例：

npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json

使用 .env 文件的示例：

# Just run without arguments - configuration will be loaded from .env
npx @ergut/mcp-bigquery-server

所需权限

你需要以下其中一样：

roles/bigquery.user （推荐）
或者两者都：

- roles/bigquery.dataViewer - roles/bigquery.jobUser

______________________________________________________________________

完整设置指南（Claude桌面版/代码版）📖

本节提供了一个全面的、分步骤的指南，帮助您将BigQuery MCP服务器与Claude Desktop或Claude Code配合使用。

🌍 多平台设置： 在Windows和Mac上都能工作？快来看看吧 CROSS_PLATFORM_CONFIG.md 翻译为中文是：《跨平台配置文件.md》适用于所有平台的配置示例。

步骤1：获取您的Google Cloud凭据

选项A：使用Google Cloud CLI（开发中最简单）

1.1。安装 Google Cloud CLI

下载地址：https://cloud.google.com/sdk/docs/install
按照您操作系统的安装向导进行操作

1.2。使用Google Cloud进行身份验证

gcloud auth application-default login

这会打开您的浏览器
使用您的Google帐户登录
授予权限
凭据存储在本地（无需密钥文件）

1.3。设置您的默认项目

gcloud config set project YOUR-PROJECT-ID

1.4。获取您的项目ID

gcloud config get-value project

保存这个项目ID - 你之后会用到它 .env 文件。

______________________________________________________________________

选项B：使用服务账户密钥（推荐用于生产环境）

1.1。导航至 Google Cloud Console

访问：https://console.cloud.google.com
选择您的项目（或创建一个新项目）

1.2。启用BigQuery API

前往：APIs与服务 → 库
搜索“BigQuery API”
如果尚未启用，请点击“启用”

1.3。创建服务账户

前往：IAM & Admin（身份与访问管理及管理员）→ 服务帐号
点击 + 创建服务账户
输入详细信息：

- 名字： bigquery-mcp-server （或您喜欢的名字） - 描述“BigQuery MCP服务器的服务账户”

点击 “创造并持续”

1.4。授予权限

在“授予此服务账户对项目的访问权限”中
点击“选择角色”下拉菜单
选择以下一项：

- 推荐: BigQuery User (角色/BigQuery用户) - 备选方案两者都加上 BigQuery Data Viewer + BigQuery Job User

点击 “继续” → “完成”

1.5。创建并下载密钥文件

点击您新创建的服务帐户
前往 “KEYS” 制表符（或按下Tab键）
点击 “ADD KEY”翻译成中文是“添加密钥” → “创建新密钥”
选择 “JSON” 格式
点击 “CREATE”翻译成中文是“创建”
一个JSON文件将自动下载
⚠️ 重要安全地保存这个文件，并且 永远不要将其提交到版本控制系统
推荐位置： C:\keys\bigquery-service-account.json (Windows) 或 ~/keys/bigquery-service-account.json (Mac/Linux)

1.6。记录您的配置详情 你需要：

项目ID在JSON键文件中找到，作为 "project_id" 在Google Cloud Console的项目下拉菜单中选择“OR”
位置您的BigQuery数据集所在的区域（例如。， US， EU， us-central1）

- 在BigQuery控制台中找到此内容 → 点击数据集 → 查看“数据位置”

密钥文件路径你刚刚下载的JSON文件的完整路径

______________________________________________________________________

步骤2：设置MCP服务器

2.1。克隆或下载此仓库

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

# OR if you downloaded as ZIP, extract and navigate to the folder
cd path/to/mcp-bigquery-server

2.2。安装依赖项

npm install

2.3。构建服务器

npm run build

2.4。创建您的 .env 配置文件

# Copy the example file
cp .env.example .env

# Now edit .env with your actual credentials

2.5。编辑 .env 文件

开放 .env 在文本编辑器中打开并填写你的值：

如果使用服务帐户密钥：

BIGQUERY_PROJECT_ID=your-project-id-here
BIGQUERY_LOCATION=US
BIGQUERY_KEY_FILE=/full/path/to/your/service-account-key.json

如果使用 Google Cloud CLI（gcloud auth）：

BIGQUERY_PROJECT_ID=your-project-id-here
BIGQUERY_LOCATION=US
# No BIGQUERY_KEY_FILE needed - it will use gcloud credentials

示例（Windows）：

BIGQUERY_PROJECT_ID=my-analytics-project-123
BIGQUERY_LOCATION=US
BIGQUERY_KEY_FILE=C:\keys\bigquery-service-account.json

示例（Mac/Linux）：

BIGQUERY_PROJECT_ID=my-analytics-project-123
BIGQUERY_LOCATION=US
BIGQUERY_KEY_FILE=/home/username/keys/bigquery-service-account.json

______________________________________________________________________

第三步：配置Claude桌面版或Claude代码版

3.1。找到您的Claude配置文件

配置文件的位置取决于您的操作系统：

Windows： %APPDATA%\Claude\claude_desktop_config.json

- 完整路径： C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

3.2。编辑配置文件

开放 claude_desktop_config.json 在文本编辑器中，并添加BigQuery MCP服务器：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/FULL/PATH/TO/mcp-bigquery-server/dist/index.js"
      ]
    }
  }
}

⚠️ 重要替换 /FULL/PATH/TO/mcp-bigquery-server 使用你克隆/下载仓库的实际绝对路径。

示例（Windows）：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "C:\\Development\\mcp-bigquery-server\\dist\\index.js"
      ]
    }
  }
}

示例（Mac/Linux）：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-bigquery-server/dist/index.js"
      ]
    }
  }
}

如果您已配置了其他MCP服务器：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/FULL/PATH/TO/mcp-bigquery-server/dist/index.js"
      ]
    },
    "other-server": {
      "command": "...",
      "args": ["..."]
    }
  }
}

3.3。保存配置文件

______________________________________________________________________

步骤4：开始使用服务器

4.1。重启 Claude 桌面/代码（环境）

彻底退出 Claude Desktop（而不仅仅是关闭窗口）
重新打开Claude桌面版

4.2。验证服务器是否已连接

查找MCP图标（通常位于右下角或工具栏）
点击它以查看已连接的服务器
你应该能看到“bigquery”被列出来

4.3。测试连接

试着问问克劳德：

"What datasets do I have in BigQuery?"

或者：

"Show me the tables in my [dataset-name] dataset"

或者：

"Query my BigQuery data: SELECT * FROM `project.dataset.table` LIMIT 10"

4.4。预期行为

克劳德将使用BigQuery MCP服务器来：

- 列出您的数据集和表格 - 显示表模式 - 执行只读SQL查询 - 以格式化的方式返回结果

______________________________________________________________________

故障排除 🔧

服务器无法连接

检查1：验证.env文件是否存在

# Navigate to your mcp-bigquery-server directory
cd /path/to/mcp-bigquery-server

# Check if .env exists
ls -la .env

# View contents (make sure values are correct)
cat .env

检查2：验证构建成功

# Make sure dist/index.js exists
ls -la dist/index.js

# If not, rebuild
npm run build

检查3：测试配置加载

# In the mcp-bigquery-server directory
node -e "require('dotenv').config(); console.log('Project:', process.env.BIGQUERY_PROJECT_ID);"

应输出： Project: your-project-id

检查4：验证服务账户密钥文件

# Check file exists (replace with your path)
ls -la /path/to/service-account-key.json

# Verify it's valid JSON
cat /path/to/service-account-key.json | head -n 5

应该显示包含JSON的（内容/数据） "type": "service_account"

检查5：验证Claude配置路径是否正确

确保路径中的（内容/设置等，根据上下文补充完整） claude_desktop_config.json 使用绝对路径
在Windows系统中，请使用双反斜杠： C:\\Development\\...
测试路径是否存在：

  node /FULL/PATH/TO/mcp-bigquery-server/dist/index.js

应显示初始化消息

认证错误

错误：“找不到密钥文件”

检查路径中的 .env 是正确且绝对的（而非相对的）
验证文件确实在那个确切的位置存在
在Windows系统中，请使用正斜杠或双反斜杠

错误：“凭据无效”

确保服务帐户密钥文件是有效的JSON格式
验证服务账户是否具有BigQuery权限
尝试重新下载密钥文件

错误：“权限被拒绝”

检查服务账户是否已 BigQuery User 角色或同等职位
验证您的项目中是否已启用BigQuery API

查询错误

错误：“仅允许读取操作”

此服务器仅支持SELECT查询
从你的SQL语句中移除任何INSERT、UPDATE、DELETE、CREATE、DROP等操作

错误：“查询超过最大计费字节限制”

默认限制为1GB
优化您的查询或指定更高的限制（使用时请注意成本）

______________________________________________________________________

安全最佳实践 🔒

永远不要将.env文件或服务账户密钥提交到git仓库

- 该 .env 文件已在其中 .gitignore - 总是要添加 *.json 钥匙到（或“通往……的关键”） .gitignore

使用最小特权原则

- 仅授予 BigQuery User 角色（只读） - 不要使用项目所有者或编辑角色

定期更换钥匙

- 定期创建新的服务账户密钥 - 从 Google Cloud Console 中删除旧密钥

在生产环境中使用服务账户

- gcloud auth 适合本地开发 - 在已部署/共享的环境中使用服务帐户

监控使用情况

- 在Google Cloud Console中检查BigQuery查询日志 - 设置账单提醒以避免意外费用

______________________________________________________________________

开发者设置（可选）🔧

想要自定义或做出贡献吗？以下是本地设置方法：

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

然后更新您的Claude桌面配置，使其指向本地构建：

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1",
        "--key-file",
        "/path/to/service-account-key.json"
      ]
    }
  }
}

当前限制 ⚠️

MCP 支持目前仅在 Claude 桌面版（开发者预览版）中可用
连接仅限于在同一台机器上运行的本地MCP服务器
查询为只读模式，处理限制为1GB
虽然两者都支持表和视图，但某些复杂的视图类型可能有其限制

支持与资源 💬

🐛 表示“虫子”或“错误（bug）”。报告问题
💡 灯泡（或表示“想法”的灯泡图标）功能请求
📖 书本文档

许可证 📝

MIT 许可证 - 查看许可证文件中有关于详情。

作者 ✍️

萨利赫·埃尔古特

赞助

此项目由以下单位自豪地赞助：

版本历史 📋

见 CHANGELOG.md 翻译为中文是：“变更日志.md”（其中“.md”表示这是Markdown格式的文件）用于查看更新和版本历史。

big query spx MCP

快速接入

详细介绍

BigQuery MCP 服务器

这是什么？ 🤔

快速示例

它是如何工作的？ 🛠️（扳手或工具的符号，可译为“扳手”或根据上下文译为“工具”等）

它能做什么？ 📊

快速入门 🚀

先决条件

选项1：通过Smithery快速安装（推荐）

选项2：手动设置

配置选项

所需权限

完整设置指南（Claude桌面版/代码版）📖

步骤1：获取您的Google Cloud凭据

选项A：使用Google Cloud CLI（开发中最简单）

选项B：使用服务账户密钥（推荐用于生产环境）

步骤2：设置MCP服务器

第三步：配置Claude桌面版或Claude代码版

步骤4：开始使用服务器

故障排除 🔧

服务器无法连接

认证错误

查询错误

安全最佳实践 🔒

开发者设置（可选）🔧

当前限制 ⚠️

支持与资源 💬

许可证 📝

作者 ✍️

赞助

版本历史 📋

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP