Which integrations are available for this server?

Retrieves metadata (datasets, tables, columns) from Google Cloud BigQuery, enables keyword search of cached metadata, executes SQL queries safely with cost control and automatic LIMIT insertion, and saves query results to local files in CSV or JSONL format.

How do I use bq_mcp_server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bq_mcp_server list datasets available in BigQuery" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bq_mcp_server

by takada-at

Overview Schema Source Related Servers Discussions Admin

Python

Remote

BigQuery MCP Server

Python Version Framework

This is a Python-based MCP (Model Context Protocol) server that retrieves dataset, table, and schema information from Google Cloud BigQuery, caches it locally, and serves it via MCP. Its primary purpose is to enable generative AI systems to quickly understand BigQuery's structure and execute queries securely.

Key Features

Metadata Management: Retrieves and caches information about BigQuery datasets, tables, and columns
Keyword Search: Supports keyword search of cached metadata
Secure Query Execution: Provides SQL execution capabilities with automatic LIMIT clause insertion and cost control
File Export: Execute queries and save results to local files in CSV or JSONL format
MCP Compliance: Offers tools via the Model Context Protocol

Related MCP server: GCP BigQuery MCP Server

MCP Server Tools

Available tools:

get_datasets - Retrieves a list of all datasets
get_tables - Retrieves all tables within a specified dataset (requires dataset_id, optionally accepts project_id)
search_metadata - Searches metadata for datasets, tables, and columns
execute_query - Safely executes BigQuery SQL queries with automatic LIMIT clause insertion and cost control
check_query_scan_amount - Retrieves the scan amount for BigQuery SQL queries
save_query_result - Executes BigQuery SQL queries and saves results to local files (CSV or JSONL format)

Tool Details

`save_query_result`

The save_query_result tool provides advanced query execution with file export capabilities:

Parameters:

sql (required): SQL query to execute
output_path (required): Local file path to save results
format (optional): Output format - "csv" (default) or "jsonl"
project_id (optional): Target GCP project ID
include_header (optional): Include header row in CSV output (default: true)

Key Features:

No Automatic LIMIT: Unlike execute_query, this tool does not automatically add LIMIT clauses to your SQL queries
Cost Control: Maintains scan amount limits (default: 1GB) and safety checks to prevent expensive queries
Security: Path validation prevents directory traversal attacks
Flexible Formats: Supports both CSV and JSONL output formats
Large Dataset Support: Handles large query results efficiently within scan limits

Example Usage:

-- Export all rows without LIMIT restriction (subject to scan amount limits)
SELECT customer_id, order_date, total_amount 
FROM `project.dataset.orders` 
WHERE order_date >= '2024-01-01'

Important Note: While this tool doesn't add LIMIT clauses, it still enforces scan amount limits for cost protection. Queries that would scan more than the configured limit (default: 1GB) will be rejected.

Installation and Environment Setup

Prerequisites

Python 3.11 or later
Google Cloud Platform account
GCP project with BigQuery API enabled

Install

uv add bq_mcp_server

pip

pip install bq_mcp_server

Installing Dependencies

This project uses uv for package management:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Configuring Option

For a list of configuration values, see:

docs/settings.md

MCP Setting

Claude Code

claude mcp add bq_mcp_server -- uvx --from git+https://github.com/takada-at/bq_mcp_server bq_mcp_server --project-ids <your project ids>

JSON

{
    "mcpServers": {
        "bq_mcp_server": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/takada-at/bq_mcp_server",
                "bq_mcp_server",
                "--project-ids",
                "<your project ids>"
            ]
        }
    }
}

Running Tests

Running All Tests

pytest

Running Specific Test Files

pytest tests/test_logic.py

Running Specific Test Functions

pytest -k test_function_name

Checking Test Coverage

pytest --cov=bq_mcp_server

Local Development

Starting the MCP Server

uv run bq_mcp_server

Starting the FastAPI REST API Server

uvicorn bq_mcp_server.adapters.web:app --reload

Development Commands

Code Formatting and Linting

# Code formatting
ruff format

# Linting checks
ruff check

# Automatic fixes
ruff check --fix

Dependency Management

# Adding new dependencies
uv add <package>

# Adding development dependencies
uv add --dev <package>

# Updating dependencies
uv sync

Available Tools

6 tools

check_query_scan_amountA

Check the scan amount of a BigQuery SQL query using dry-run without executing it.

Args:
    sql: The SQL query to check
    project_id: Optional project ID to use for the query (defaults to first configured project)

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes
`project_id`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description effectively discloses the tool's behavior: it performs a dry-run without executing, meaning it is read-only and has no side effects. It also mentions the default behavior for the project_id parameter. However, it does not specify return format (e.g., bytes, MB) or other behavioral traits like error handling or quotas.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two sentences for the main purpose plus a bullet list for parameters. Every sentence is informative, no fluff or repetition. The structure clearly front-loads the key action and then details parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with only two parameters and no output schema, the description covers essential information: what it does, parameters, and default behavior. However, it lacks details about the return value (e.g., whether the scan amount is in bytes or other units) and does not address potential error scenarios. Minor completeness gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear, meaningful descriptions for both parameters: 'sql: The SQL query to check' and 'project_id: Optional project ID to use for the query (defaults to first configured project)'. This adds significant value beyond the schema types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Check the scan amount of a BigQuery SQL query using dry-run without executing it.' It specifies the verb (check), resource (scan amount of a BigQuery SQL query), and method (dry-run). This distinguishes it from sibling tools like execute_query which actually runs queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for estimating data scanned before execution, but it does not explicitly state when to use this tool versus alternatives. There is no mention of when not to use it or reference to sibling tools like execute_query for running the query. The guidance is adequate but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_queryA

Execute BigQuery SQL with automatic safety checks and LIMIT clause management.

Args:
    sql: The SQL query to execute
    project_id: Optional project ID to use for the query (defaults to first configured project)

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes
`project_id`	No

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It mentions safety checks but does not specify what they entail, what destructive actions may occur, or what the result format is. A query execution tool should disclose read/write behavior and error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: one sentence for the tool and two lines for parameters. It is front-loaded with the key purpose and safety aspect, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool executes arbitrary SQL, which has complex behavior, yet the description lacks information about return values, whether results are streamed, pagination, error codes, or specifics of the safety checks. With no output schema or annotations, this is insufficient for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage (no descriptions for parameters), but the description explains 'sql: The SQL query to execute' and 'project_id: Optional... defaults to first configured project'. This adds meaningful context beyond the raw schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute BigQuery SQL' which combines a specific verb and resource. Siblings like get_datasets and get_tables have distinct purposes, so this tool stands out as the execution tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions automatic safety checks and LIMIT clause management but does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage is implied but not contrasted with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_datasetsA

Get list of all datasets

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description only states 'get list of all datasets', lacking any behavioral details like read-only status, pagination, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence with no superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a no-parameter list tool, but could explain the return format (e.g., array of dataset names) to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, schema coverage is 100%, so the baseline of 4 applies; description adds no extra param info, but it is not needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get list of all datasets' clearly states the verb (Get) and resource (datasets), distinguishing it from siblings like get_tables or execute_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternatives provided, but the simplicity of the tool makes it obvious; minimal guidance is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tablesC

Get list of all tables in a dataset

ParametersJSON Schema

Name	Required	Description	Default
`dataset_id`	Yes
`project_id`	No

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only list operation but does not mention whether it requires permissions, handles missing datasets, or has any side effects. The description is silent on what happens if the dataset doesn't exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no redundancy. However, it may be too short, sacrificing useful details for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and 0% parameter documentation, the description is severely incomplete. It does not describe return values, parameter formats, or error conditions, making it inadequate for reliable tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no meaning to the parameters. It does not explain dataset_id or project_id roles, leaving the agent without guidance on how to use them correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Get list) and resource (all tables in a dataset). It distinguishes the tool from sibling like get_datasets, which lists datasets, not tables. However, it does not specify if it returns table names, schemas, or other metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as search_metadata for filtered table searches. No context on prerequisites or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_query_resultA

Execute BigQuery SQL and save results to a local file.

Args:
    sql: The SQL query to execute
    output_path: Path where to save the results
    format: Output format - 'csv' or 'jsonl' (defaults to 'csv')
    project_id: Optional project ID to use for the query (defaults to first configured project)
    include_header: Include header row in CSV output (ignored for JSONL, defaults to True)

ParametersJSON Schema

Name	Required	Default
`sql`	Yes
`output_path`	Yes
`format`	No	csv
`project_id`	No
`include_header`	No

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It mentions execution and saving but does not disclose side effects like cost, data deletion, or error handling. Basic transparency but insufficient depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and follows a clean docstring structure with Args. No unnecessary sentences, though it could be slightly more compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description is fairly complete but lacks return value details and error handling. Adequate but with gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates fully. It explains each parameter: sql (query), output_path (save path), format (csv/jsonl defaults), project_id (optional), include_header (for CSV). Adds meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Execute' and 'save' with resources 'BigQuery SQL' and 'local file'. It distinguishes from siblings like 'execute_query' and 'check_query_scan_amount' by specifying the saving aspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for saving query results to a file but does not explicitly state when to use this tool versus alternatives. It lacks exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_metadataC

Search metadata for datasets, tables, and columns

ParametersJSON Schema

Name	Required	Description	Default
`key`	Yes

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only says 'search metadata' without specifying if it's read-only, what is returned, or any constraints. The agent gains little insight beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but under-specified. It lacks critical details needed for correct usage, making it too sparse rather than efficiently informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter, no output schema, and no annotations, the description fails to provide adequate context. It does not explain the parameter's format, the search behavior, or the return value, leaving the tool largely opaque.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one required parameter 'key' of type string, with 0% schema description coverage. The description does not explain what 'key' represents (e.g., search term, exact match, pattern), leaving the agent confused about how to use it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches metadata for datasets, tables, and columns. It uses a specific verb (search) and resource (metadata), and distinguishes from sibling tools like get_datasets and get_tables which list all items rather than searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for different scenarios, leaving the agent without context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.2.2Jun 10, 2026
- First observedcheck_query_scan_amount
- First observedexecute_query
- First observedget_datasets
- First observedget_tables
- First observedsave_query_result
- First observedsearch_metadata

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-06-10 10:05 across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: checking query cost, executing queries, listing datasets/tables, saving results, and searching metadata. No two tools overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., 'check_query_scan_amount', 'execute_query', 'get_datasets'), making them predictable and easy to distinguish.

Tool Count5/5

With 6 tools, the server is well-scoped for BigQuery query and metadata operations. Each tool serves a necessary function without redundancy or bloat.

Completeness5/5

The tool set covers all core workflows for BigQuery exploration: listing resources, checking query cost, executing queries, saving results, and searching metadata. No obvious gaps are present for this domain.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Google Big Query A
com.googleapis.bigquery
The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.
Databases Cloud Platforms Search
83
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
thoughtsOAuth
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102

Related MCP Servers

BigQuery MCP Server
Databases Cloud Platforms
takuya0206
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables LLMs to understand BigQuery dataset structures and execute SQL queries.
Updated a year ago (2025-04-02 00:36 UTC)
9 npm
5
MIT
GCP BigQuery MCP Server
Databases Cloud Platforms Developer Tools
erayguner
A
license
Not graded
quality
C
maintenance
Enterprise-grade MCP server for Google Cloud BigQuery with keyless Workload Identity Federation authentication, enabling secure SQL query execution, dataset management, and schema inspection with comprehensive audit logging and encryption.
Updated 2 months ago (2026-08-01 08:25 UTC)
MIT
bq-readonly-mcp
Databases Cloud Platforms
mariadb-RupeshBiswas
A
license
Not graded
quality
B
maintenance
A read-only BigQuery MCP server with auto-LIMIT injection, dry-run cost guard, and ADC authentication. Allows safe SQL querying of BigQuery by LLMs without risk of data modification or unexpected costs.
Updated a month ago (2026-08-21 07:36 UTC)
1
MIT
MCP BigQuery Server
Databases AI & Machine Learning Search
rodneyelmore
A
license
Not graded
quality
D
maintenance
Production-ready MCP server for BigQuery that translates natural language questions to SQL, executes queries securely, and delivers results via stdio or HTTP for integration with GitHub Copilot, Power BI, and web applications.
Updated 7 months ago (2026-02-04 23:36 UTC)
689 npm
MIT