mcp-bigquery

Безопасное исследование BigQuery через Model Context Protocol

Документация | Быстрый старт | Примеры

Обзор

mcp-bigquery — это сервер Model Context Protocol (MCP), который позволяет ИИ-ассистентам (таким как Claude) безопасно взаимодействовать с Google BigQuery.

Ключевые возможности

• Безопасное выполнение: Все операции строго ограничены проверкой dry-run. Сервер никогда не выполняет запросы, которые изменяют данные или влекут затраты на выполнение.

• Прозрачность затрат: Предоставляет оценку стоимости запросов и объёма обрабатываемых данных до выполнения.

• Статический анализ: Анализирует зависимости запросов и проверяет синтаксис SQL.

• Исследование схемы: Просмотр наборов данных, таблиц и столбцов.

Бизнес-ценность

Related MCP server: mcp-bigquery-dryrun

Быстрый старт

Шаг 1: Установка

Установите пакет с помощью pip:

pip install mcp-bigquery

Шаг 2: Аутентификация

Настройте аутентификацию Google Cloud Platform:

# For user account authentication
gcloud auth application-default login

# For service account authentication
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Шаг 3: Конфигурация Claude Desktop

Настройте сервер в файле конфигурации Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте следующую запись:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Шаг 4: Проверка

Перезапустите Claude Desktop и выполните следующие запросы, чтобы проверить настройку:

• «Какие наборы данных доступны в моём проекте BigQuery?»

• «Можешь оценить стоимость: SELECT * FROM dataset.table»

• «Покажи схему таблицы users»

Доступные инструменты

Проверка и анализ SQL

Обнаружение схемы

[!ВАЖНО] Инструмент bq_preview_table использует client.list_rows (API: tabledata.list) для прямого получения строк, что обеспечивает нулевое сканирование байт и отсутствие затрат на выполнение. Чтобы предотвратить непреднамеренную утечку конфиденциальной информации (например, ПДн) в LLM, этот инструмент по умолчанию отключён. Вы должны явно включить его, установив MCP_BQ_ENABLE_PREVIEW=true в конфигурации окружения.

Конфигурация

Переменные окружения

Пример файла .env

Для локального тестирования или сред разработки вы можете определить эти переменные в файле .env:

BQ_PROJECT=your-gcp-project-id
BQ_LOCATION=asia-northeast1
SAFE_PRICE_PER_TIB=5.0
LOG_LEVEL=WARNING
MCP_BQ_ENABLE_PREVIEW=true

Полный пример конфигурации Claude Desktop

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "my-production-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "6.0",
        "LOG_LEVEL": "WARNING",
        "MCP_BQ_ENABLE_PREVIEW": "true"
      }
    }
  }
}

Устранение неполадок

Сопоставленные ошибки и их решения

Ошибка аутентификации

Error: Could not automatically determine credentials

• Решение: Повторно пройдите аутентификацию с помощью командной строки:

  gcloud auth application-default login

Отказано в доступе

Error: User does not have bigquery.tables.get permission

• Решение: Предоставьте роль BigQuery Data Viewer целевой учётной записи:

  gcloud projects add-iam-policy-binding YOUR_PROJECT \
    --member="user:your-email@example.com" \
    --role="roles/bigquery.dataViewer"

Отсутствует идентификатор проекта

Error: Project ID is required

• Решение: Убедитесь, что переменная BQ_PROJECT корректно задана в вашей конфигурации.

Примеры использования

Пример 1: Проверка затрат перед выполнением

# Before running an expensive query...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"

# First, check the cost
result = bq_dry_run_sql(sql=query)
print(f"Estimated cost: ${result['usdEstimate']}")
print(f"Data processed: {result['totalBytesProcessed'] / 1e9:.2f} GB")

# Output:
# Estimated cost: $12.50
# Data processed: 2500.00 GB

Пример 2: Понимание структуры таблицы

# Check table schema
result = bq_describe_table(
    dataset_id="your_dataset",
    table_id="users"
)

# Output:
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
#     ├── name (STRING)
#     └── age (INTEGER)

Пример 3: Отслеживание зависимостей данных

# Understand query dependencies
query = """
WITH user_stats AS (
  SELECT user_id, COUNT(*) as order_count
  FROM orders
  GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""

result = bq_extract_dependencies(sql=query)

# Output:
# Tables: ['orders', 'users']
# Columns: ['user_id', 'name', 'id']
# Dependency Graph:
#   orders → user_stats → final_result
#   users → final_result

Статус проекта и история версий

Разработка и вклад

Инструкции по настройке локальной разработки и политике вклада см. в руководстве CONTRIBUTING.md.

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

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

# Execute the test suite
pytest tests/

Лицензия

Этот проект распространяется под лицензией MIT. Подробнее см. в LICENSE.