bq_mcp_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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
BigQuery MCP Server
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 datasetsget_tables- Retrieves all tables within a specified dataset (requires dataset_id, optionally accepts project_id)search_metadata- Searches metadata for datasets, tables, and columnsexecute_query- Safely executes BigQuery SQL queries with automatic LIMIT clause insertion and cost controlcheck_query_scan_amount- Retrieves the scan amount for BigQuery SQL queriessave_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 executeoutput_path(required): Local file path to save resultsformat(optional): Output format -"csv"(default) or"jsonl"project_id(optional): Target GCP project IDinclude_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 queriesCost 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
uv add bq_mcp_serverpip
pip install bq_mcp_serverInstalling 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 syncConfiguring Option
For a list of configuration values, see:
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
pytestRunning Specific Test Files
pytest tests/test_logic.pyRunning Specific Test Functions
pytest -k test_function_nameChecking Test Coverage
pytest --cov=bq_mcp_serverLocal Development
Starting the MCP Server
uv run bq_mcp_serverStarting the FastAPI REST API Server
uvicorn bq_mcp_server.adapters.web:app --reloadDevelopment Commands
Code Formatting and Linting
# Code formatting
ruff format
# Linting checks
ruff check
# Automatic fixes
ruff check --fixDependency Management
# Adding new dependencies
uv add <package>
# Adding development dependencies
uv add --dev <package>
# Updating dependencies
uv syncAvailable Tools
6 toolscheck_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)
Inputs: sql (required), project_id.
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)
Inputs: sql (required), project_id.
get_datasetsA
Get list of all datasets
Inputs: no named parameters.
get_tablesC
Get list of all tables in a dataset
Inputs: dataset_id (required), project_id.
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)
Inputs: sql (required), output_path (required), format, project_id, +1 more.
search_metadataC
Search metadata for datasets, tables, and columns
Inputs: key (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
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.
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.
With 6 tools, the server is well-scoped for BigQuery query and metadata operations. Each tool serves a necessary function without redundancy or bloat.
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
Related MCP Connectors
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
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.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to understand BigQuery dataset structures and execute SQL queries.125 npm5MIT
- AlicenseNot gradedqualityCmaintenanceEnterprise-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.MIT
- AlicenseNot gradedqualityCmaintenanceA 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.1MIT
- AlicenseNot gradedqualityDmaintenanceProduction-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.264 npmMIT