BigQuery MCP 服务器

<div align="center"> <img src="assets/mcp-bigquery-server-logo.png" alt="BigQuery MCP Server Logo" width="400"/> </div>

这是什么？ 🤔

这是一个让你的 LLM（例如 Claude）直接与你的 BigQuery 数据对话的服务器！ 可以把它想象成一个友好的翻译器，位于你的 AI 助手和你的数据库之间，确保它们可以安全有效地聊天。

快速示例

你：“上个月我们排名前 10 的客户是谁？”
Claude：*查询你的 BigQuery 数据库，并用简单的英语给你答案*

无需再手动编写 SQL 查询 - 只需以自然的方式与你的数据聊天！

它如何工作？ 🛠️

此服务器使用模型上下文协议 (MCP)，它就像 AI 数据库通信的通用翻译器。 虽然 MCP 旨在与任何 AI 模型一起使用，但目前它在 Claude Desktop 中以开发者预览版提供。

以下是您需要做的：

1. 设置身份验证（见下文）
2. 将您的项目详细信息添加到 Claude Desktop 的配置文件
3. 开始以自然的方式与您的 BigQuery 数据聊天！

它可以做什么？ 📊

• 只需用简单的英语提问即可运行 SQL 查询
• 访问数据集中的表和物化视图
• 使用资源类型的清晰标签（表与视图）浏览数据集模式
• 在安全限制内分析数据（默认情况下为 1GB 查询限制）
• 确保您的数据安全（只读访问）

快速开始 🚀

前提条件

• Node.js 14 或更高版本
• 启用了 BigQuery 的 Google Cloud 项目
• 已安装 Google Cloud CLI 或服务帐户密钥文件
• Claude Desktop（目前唯一支持的 LLM 界面）

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

要通过 Smithery 为 Claude Desktop 自动安装 BigQuery MCP Server，请在您的终端中运行以下命令：

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

安装程序将提示您：

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

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

选项 2：手动设置

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

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

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

     gcloud auth application-default login
     

   • 使用服务帐户（推荐用于生产）：

     # 保存您的服务帐户密钥文件并使用 --key-file 参数
     # 记住要保护您的服务帐户密钥文件，并且永远不要将其提交到版本控制
     

2. 添加到您的 Claude Desktop 配置 将此添加到您的 claude_desktop_config.json：

   • 基本配置：

     {
       "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"
           ]
         }
       }
     }
     

3. 开始聊天！ 打开 Claude Desktop 并开始询问有关您数据的问题。

命令行参数

服务器接受以下参数：

• --project-id：（必需）您的 Google Cloud 项目 ID
• --location：（可选）BigQuery 位置，默认为“us-central1”
• --key-file：（可选）服务帐户密钥 JSON 文件的路径

使用服务帐户的示例：

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

需要的权限

您需要以下权限之一：

• roles/bigquery.user（推荐）
• 或两者：
  • roles/bigquery.dataViewer
  • roles/bigquery.jobUser

开发者设置（可选） 🔧

想要自定义或贡献？ 以下是如何在本地设置它：

# 克隆并安装
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# 构建
npm run build

然后更新您的 Claude Desktop 配置以指向您的本地构建：

{
  "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 Desktop（开发者预览版）中可用
• 连接仅限于在同一台机器上运行的本地 MCP 服务器
• 查询是只读的，具有 1GB 的处理限制
• 虽然支持表和视图，但某些复杂的视图类型可能存在限制

支持与资源 💬

• 🐛 报告问题
• 💡 功能请求
• 📖 文档

许可证 📝

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

作者 ✍️

Salih Ergüt

赞助

该项目由以下机构自豪地赞助：

<div align="center"> <a href="https://www.oredata.com"> <img src="assets/oredata-logo-nobg.png" alt="OREDATA" width="300"/> </a> </div>

版本历史 📋

有关更新和版本历史，请参阅 CHANGELOG.md。