AI导哈

BigQuery SQL验证工具

一个用于验证BigQuery SQL语法并进行干运行分析的MCP服务器工具，提供成本估算和模式预览功能。

  • by caron14
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 caron14/mcp-bigquery-dryrun

使用说明

mcp bigquery dryrun

这 mcp-bugquery-dryrun 该包为BigQuery SQL验证和模拟运行分析提供了一个最小的MCP服务器。该服务器提供了两种工具，用于验证和分析BigQuery SQL查询，而无需执行它们。

**重要提示：此服务器不执行查询。所有操作仅为模拟运行。成本估算是基于处理字节的近似值**

特性

  • SQL验证：在不运行查询的情况下检查BigQuery SQL语法
  • 干运行分析：获取成本估算、参考表和架构预览
  • 参数支持：验证参数化查询
  • 成本估算：根据处理的字节数计算美元估算值

快速开始

先决条件

  • Python 3.10+
  • 启用BigQuery API的Google云SDK
  • 已配置应用程序默认凭据

安装

来自PyPI（推荐）

# Install from PyPI
pip install mcp-bigquery-dryrun

# Or with uv
uv pip install mcp-bigquery-dryrun

来源

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

# Install with uv (recommended)
uv pip install -e .

# Or install with pip
pip install -e .

认证

设置应用程序默认凭据：

gcloud auth application-default login

或者使用服务帐户密钥：

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

配置

环境变量

变量 描述 默认值
BQ_PROJECT GCP项目ID 来自ADC
BQ_LOCATION BigQuery位置（例如，美国、欧盟、亚洲东北1） 无
SAFE_PRICE_PER_TIB 成本估算的每TiB默认价格 5.0

Claude代码集成

添加到您的Claude代码配置中：

{
  "mcpServers": {
    "bq-dryrun": {
      "command": "mcp-bigquery-dryrun",
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

或者，如果从源代码安装：

{
  "mcpServers": {
    "bq-dryrun": {
      "command": "python",
      "args": ["-m", "mcp_bigquery_dryrun"],
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

工具

bq_validate_sql

在不执行查询的情况下验证BigQuery SQL语法。

输入：

{
  "sql": "SELECT * FROM dataset.table WHERE id = @id",
  "params": {"id": "123"}  // Optional
}

成功响应：

{
  "isValid": true
}

错误响应：

{
  "isValid": false,
  "error": {
    "code": "INVALID_SQL",
    "message": "Syntax error at [3:15]",
    "location": {
      "line": 3,
      "column": 15
    },
    "details": [...]  // Optional
  }
}

bq_dry_run_sql

执行模拟运行以获取成本估算和元数据，而无需执行查询。

输入：

{
  "sql": "SELECT * FROM dataset.table",
  "params": {"id": "123"},  // Optional
  "pricePerTiB": 6.0  // Optional, overrides default
}

成功响应：

{
  "totalBytesProcessed": 1073741824,
  "usdEstimate": 0.005,
  "referencedTables": [
    {
      "project": "my-project",
      "dataset": "my_dataset",
      "table": "my_table"
    }
  ],
  "schemaPreview": [
    {
      "name": "id",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "mode": "REQUIRED"
    }
  ]
}

错误响应：

{
  "error": {
    "code": "INVALID_SQL",
    "message": "Table not found: dataset.table",
    "details": [...]  // Optional
  }
}

例子

验证简单查询

# Tool: bq_validate_sql
{
  "sql": "SELECT 1"
}
# Returns: {"isValid": true}

使用参数进行验证

# Tool: bq_validate_sql
{
  "sql": "SELECT * FROM users WHERE name = @name AND age > @age",
  "params": {
    "name": "Alice",
    "age": 25
  }
}

获取成本估算

# Tool: bq_dry_run_sql
{
  "sql": "SELECT * FROM `bigquery-public-data.samples.shakespeare`",
  "pricePerTiB": 5.0
}
# Returns bytes processed, USD estimate, and schema

分析复杂查询

# Tool: bq_dry_run_sql
{
  "sql": """
    WITH user_stats AS (
      SELECT user_id, COUNT(*) as order_count
      FROM orders
      GROUP BY user_id
    )
    SELECT * FROM user_stats WHERE order_count > 10
  """
}

测试

使用pytest运行测试：

# Run all tests (requires BigQuery credentials)
pytest tests/

# Run only tests that don't require credentials
pytest tests/test_min.py::TestWithoutCredentials

发展

# Install development dependencies
uv pip install -e ".[dev]"

# Run the server locally
python -m mcp_bigquery_dryrun

# Or using the console script
mcp-bigquery-dryrun

局限性

  • 无查询执行：此服务器仅执行模拟运行和验证
  • 成本估算：美元估计值是基于处理字节的近似值
  • 参数类型：初始实现将所有参数视为STRING类型
  • 缓存已禁用：查询始终使用 use_query_cache=False 为了获得准确的估计

许可证

阿帕奇-2.0

更新日志

0.1.0 (2024-08-12)

  • 初始版本

相关 MCP