flin-bigquery-mcp
Explore BigQuery metadata and run bounded, read-only GoogleSQL SELECT queries with cost controls.
Check local configuration and connection/auth status without network access or query costs.
List accessible projects, datasets, tables, and views.
Inspect dataset location, description, and labels.
Inspect table schemas, row counts, sizes, partitioning, and clustering.
Preview bounded rows from physical tables without running a SQL query job.
Dry-run a single SELECT to validate it and estimate scanned bytes.
Submit a bounded SELECT query job with named scalar parameters and a maximum bytes-billed limit.
Poll query jobs, fetch result pages, and paginate through results.
Use named OAuth accounts or ADC, with project, location, and account selection where supported.
Provides tools for exploring BigQuery projects, datasets, tables, and schemas; previewing table rows; dry-running and executing bounded read-only GoogleSQL SELECT queries; and polling query results, with OAuth/ADC authentication and byte-billing limits.
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., "@flin-bigquery-mcp show me the schema for the orders table in the sales dataset"
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.
flin-bigquery-mcp
MCP server for exploring Google BigQuery and running bounded, read-only GoogleSQL queries. Follows the Python/FastMCP, desktop OAuth, multi-account token storage and uv packaging conventions of flin Search Console MCP and flin Keyword Planner MCP.
Claude Desktop on Mac (Apple Silicon M1 or newer)
Download flin-bigquery-mcp.mcpb and open it with a current Claude Desktop that supports
uvextensions. Alternatively select the file in Claude Desktop's local extension installation dialog. Versioned downloads and checksums remain available. Intel Macs are also supported; source installation for other MCP clients is below.Enter the Google Desktop OAuth client ID and secret supplied by your administrator/password manager. Set the intended billing project and dataset location (for example
EU) when provided. Keep maximum bytes billed at its default1073741824(1 GiB per query), unless your administrator deliberately specifies another limit. Never enter your Google account password in the extension settings.Ask Claude: “Call connection_status for flin BigQuery.” This checks local setup only, without opening a browser or incurring query costs.
configuration_status: configuredmeans the local configuration is valid, not that Google permissions have been verified.Ask: “Call list_projects with page_size 1.” Complete Google sign-in in the browser if prompted. This metadata request does not create a query job.
Ask: “Call list_datasets with project_id set to my intended data project and page_size 1.” A successful response, including an empty list, verifies that metadata request for that identity/project. It does not prove access to every dataset or permission to create query jobs. The administrator grants BigQuery Data Viewer on the intended datasets and BigQuery Job User on the billing/job project; these may be different projects.
SELECT can incur costs even though it does not change source data. run_query creates a potentially billable BigQuery job. The default hard ceiling is 1 GiB scanned/billed bytes per query, not a monetary budget, total-session limit or complete cap on remote-function/external charges. A tool argument can lower this ceiling but cannot raise it. No live query is needed for the connection test above.
Updates, versions and recovery
Every published server version ships on PyPI and with a fresh Mac installer on GitHub. After the first installation, fully quit and reopen Claude Desktop to load a compatible stable PyPI update. Running conversations are not interrupted; existing settings and token locations are preserved.
Extension version identifies the installed launcher/form. connection_status.server_version (also health_check.server_version) identifies the actual running server. These versions may differ after an automatic update.
The launcher introduced in 0.1.3 accepts >=0.1.3,<0.2, excludes prereleases, and uses Python 3.12. The compatibility contract is the existing entry point, configuration variables, token locations and additive MCP tool discovery; these are checked on release. A later 0.2 line is not assumed compatible. Existing 0.1.1/0.1.2 launchers can obtain server 0.1.3 automatically, but their older manifests have no upper bound: import the new package once to adopt the bounded update policy. New mandatory launcher/UI/runtime changes can require a separately announced one-time import; ordinary compatible server updates do not.
The launcher needs internet access to check PyPI at startup. If the registry is unavailable it reports a startup error; it does not silently fall back to a cached version. Restore connectivity and restart first. If PyPI remains unavailable, an administrator can use the prepared-checkout fallback below; Google access still requires internet. Tokens should not be deleted to troubleshoot a package-download problem. The .mcpb is an unsigned local extension, not an Apple-notarized app.
Related MCP server: BigQuery MCP Server
Administrator setup and other MCP clients
Enable the BigQuery API in your Google Cloud project and configure billing for query jobs.
Grant the Google account BigQuery Job User (
roles/bigquery.jobUser) on the job/billing project and BigQuery Data Viewer (roles/bigquery.dataViewer) on the datasets to read. Metadata discovery also depends on the account's project/dataset permissions. Avoid using an admin identity.Configure the OAuth consent screen. For an external app in testing, add your Google account as a test user.
Create an OAuth client of type Desktop app. Use its client ID and secret below. The local loopback callback is managed by the server.
Install uv and clone this repository. Add this entry to your MCP client's configuration:
{
"mcpServers": {
"flin-bigquery-mcp": {
"command": "uv",
"args": [
"run", "--directory", "/absolute/path/to/flin-bigquery-mcp",
"--locked", "flin-bigquery-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "your-desktop-client-id",
"GOOGLE_CLIENT_SECRET": "your-desktop-client-secret",
"GOOGLE_BIGQUERY_PROJECT": "your-billing-project",
"GOOGLE_BIGQUERY_LOCATION": "EU"
}
}
}
}Replace the path and values, then restart the client. health_check checks configuration locally. list_projects or the first data call opens Google sign-in when needed. Tokens are saved locally and refreshed automatically. OAuth waits for up to three minutes; retry the tool if sign-in expires.
This is a local stdio server, usable with clients such as Claude Desktop and Codex that support local MCP processes. No HTTP endpoint or cloud deployment is provisioned.
The published package can be used with "command": "uvx", "args": ["flin-bigquery-mcp@latest"].
Tools
Tool | Purpose |
| Common local status and actual server version; no network, browser, refresh or query job |
| Local settings and saved-token status; does not verify Google access |
| One page of accessible projects |
| One page of datasets in a project |
| Dataset location, description and labels |
| One page of tables and views |
| Nested schema, row count, size, partitioning and clustering |
| Bounded rows from a physical table without running a SQL query |
| Validate a single SELECT and estimate scanned bytes |
| Validate and submit a bounded SELECT; returns a job reference |
| Poll a query job and page through its results |
connection_status always returns server_version, configuration_status (configured/incomplete), auth_status, live_access and next_step. With a saved token or ADC, auth_status is unknown: only Google can verify that credentials are still accepted. Without an OAuth token it is unauthenticated. live_access is always not_checked for this local-only tool, even after a separate successful metadata request. It does not return credentials, local paths or project/data identifiers. The existing health_check fields remain available.
All data tools support account. Project-specific tools use project_id, falling back to GOOGLE_BIGQUERY_PROJECT. Pass dataset and table IDs separately, without project prefixes. list_projects works without a default project. Query project_id determines where the job is created and billed; fully qualified SQL can read another accessible project.
Example workflow
health_check, thenlist_projects.list_datasets,get_dataset(check its location),list_tables,get_table.preview_tableto inspect a few rows, ordry_run_queryto estimate a query.run_queryonce, thenget_query_resultswith the returnedjob_id,project_id,locationand the same account.If
job_completeis false, poll again later. For subsequent pages, passnext_page_tokenunchanged. Do not callrun_queryagain to poll.
A parameterized query:
{
"sql": "SELECT event_name, COUNT(*) AS events FROM `data-project.analytics.events_*` WHERE _TABLE_SUFFIX BETWEEN @start_date AND @end_date GROUP BY event_name ORDER BY events DESC LIMIT 20",
"project_id": "billing-project",
"location": "EU",
"parameters": [
{"name": "start_date", "type": "STRING", "value": "20261001"},
{"name": "end_date", "type": "STRING", "value": "20261007"}
],
"maximum_bytes_billed": 1073741824
}Named scalar parameters are supported; ARRAY/STRUCT parameters are not yet exposed. Result pages contain at most 1,000 rows (default 100); previews default to 20. A page token is tied to its resource/job and account. Results expire according to BigQuery's anonymous result-table retention. Dates/times use ISO strings, NUMERIC/BIGNUMERIC use decimal strings, BYTES use base64, and non-finite floats use strings. Arrays and nested records are preserved. Large STRING/BYTES cells can still produce large responses despite the row limit.
Query controls and permissions
Every execution is preceded by a Google BigQuery dry run. Google's parsed
statement_typemust beSELECT. Scripts, stored procedure calls, DDL, DML, exports and unknown statement types are rejected before execution.Default hard ceiling: 1 GiB (1,073,741,824 bytes) per query. Set
GOOGLE_BIGQUERY_MAX_BYTES_BILLEDto change it. Tool arguments may lower but cannot raise this ceiling.Both the dry-run estimate and the submitted job are checked/bounded. Estimates may be incomplete for external or federated sources.
maximum_bytes_billedlimits BigQuery on-demand bytes, not every possible external, remote-function, ML or reservation charge.A SQL
LIMITlimits output rows, not scanned bytes. Filter partitions and select only needed columns.run_queryis marked non-idempotent and not read-only in MCP annotations because it creates a potentially billable job. Its allowed SQL only reads data. Polling results does not submit new queries.The Google client uses
jobs.insert, which requires thehttps://www.googleapis.com/auth/bigqueryscope. That scope is broader than the server's tool surface. IAM permissions are the underlying access boundary; the server deliberately exposes no write operations or user-supplied destination/job configuration.SELECT queries can invoke existing views, routines or remote functions allowed by IAM. SQL classification does not sandbox their downstream effects. Use a dedicated identity with only the intended dataset/job permissions.
Query submission uses a generated job ID and disables automatic job re-execution. If a transport error occurs after submission, check BigQuery job history before manually retrying to avoid duplicate charges.
Authentication and settings
Variable | Default / use |
|
|
| Required in OAuth mode |
| Default metadata and billing/job project; otherwise pass |
| Optional location ( |
|
|
| Default account's token file |
| Named account token directory; defaults to the default token's directory |
|
|
| Standard Google ADC credential file setting |
Default OAuth token paths:
macOS:
~/Library/Application Support/flin-bigquery-mcp/token.jsonLinux:
~/.config/flin-bigquery-mcp/token.jsonWindows:
%APPDATA%\flin-bigquery-mcp\token.json
Use account: "work" to keep another account in work.json. Account names allow letters, digits, _, -, . and cannot alias the default token file. Tokens are written atomically, with private file permissions on POSIX. Reads reject symlinks, hard links, non-regular files, oversized or malformed token data, and (on POSIX) files owned by another user or accessible to group/others. OAuth explicitly enables PKCE. Use a private directory owned by your user. Named accounts refer to separate sign-ins, not Google account IDs.
For service accounts, workload identity, or existing gcloud auth application-default login credentials:
{
"GOOGLE_BIGQUERY_AUTH_MODE": "adc",
"GOOGLE_BIGQUERY_PROJECT": "your-billing-project",
"GOOGLE_BIGQUERY_LOCATION": "EU"
}Optionally set GOOGLE_APPLICATION_CREDENTIALS to a credential file outside the repository. ADC mode does not support named account values. health_check always returns adc_not_checked with ok: false in ADC mode; verify access through a data tool. It never contacts metadata servers or opens a browser to probe ADC. Grant the ADC identity the same minimal BigQuery roles.
Prepared-checkout fallback
For a PyPI outage, an administrator may use an already reviewed checkout of a known stable release whose locked dependencies and Python runtime were installed beforehand. Keep the same Google settings and token paths, and temporarily use this MCP command instead of the extension:
uv run --offline --locked --directory /absolute/path/to/prepared-checkout flin-bigquery-mcpThis is an explicit fallback to that checkout's version, not an automatic downgrade. It fails if the needed runtime/dependencies are not already available. Google API access still needs connectivity. Return to the normal extension and restart once PyPI recovers. For deployment help see SUPPORT.md.
Development
uv sync --locked --extra dev
uv run pytest
uv run ruff check src tests scripts mcpb
uv run ruff format --check src tests scripts mcpb
uv build --out-dir dist/python
uv run python scripts/build_mcpb.py
uv run python scripts/check_mcpb.py dist/mcpb --server-wheel dist/python.env.example documents configuration. The server does not implicitly load .env; use client env settings or uv run --env-file .env flin-bigquery-mcp for local development. Never commit credentials or tokens.
Tests run without credentials and mock Google API calls. They cover OAuth refresh/storage, account isolation, query rejection, byte ceilings, pagination, serialization, sanitized errors, and a real stdio MCP handshake/tool call. See testing for the optional live check.
See security policy, security review, release instructions, privacy, and support.
Troubleshooting
missing_configuration/invalid_configuration: check the selected authentication mode, required OAuth values, project, account name and positive byte ceiling.authentication_failed/invalid_token_file: check that the token is a regular file owned by you, with mode0600on macOS/Linux, in a directory that other users cannot modify. Do not use linked token files. If a token was exposed to others, revoke it and sign in again.authentication_required: complete Google sign-in or configure ADC. External OAuth apps in testing may require renewed consent.permission_denied: check API enablement, job-user and data-viewer access, billing and quotas.not_found: check IDs and the returned job location. An EU job cannot be fetched as a US job.query_rejected: use a single SELECT (including CTEs), not a script or write operation.cost_limit_exceeded: reduce scanned columns/date partitions or deliberately change the configured server ceiling.invalid_request: check SQL, parameter types and region. Detailed SQL-bearing upstream errors are deliberately not returned to the model; inspect the Google Cloud console when needed.
Official references
Available Tools
11 toolsconnection_statusARead-onlyIdempotent
Report local setup only: no network, browser, token refresh or query costs.
A saved token cannot prove Google still accepts it. Use list_datasets for an explicit metadata access test; this status call never claims live access.
Inputs: account. Returns: object
dry_run_queryARead-onlyIdempotent
Validate a single SELECT and estimate bytes without executing it. Named parameters use @name in SQL.
Inputs: sql (required), account, location, parameters, +2 more. Returns: object
get_datasetBRead-onlyIdempotent
Get dataset location, description and labels. dataset_id must not include the project prefix.
Inputs: dataset_id (required), account, project_id. Returns: object
get_query_resultsARead-onlyIdempotent
Poll a query job or read one result page. Reuse project_id, location and account from submission.
If job_complete is false, call again later. Pass next_page_token unchanged to read the next page. NUMERIC values are decimal strings, dates are ISO strings, bytes are base64 strings.
Inputs: job_id (required), account, location, page_size, +2 more. Returns: object
get_tableBRead-onlyIdempotent
Read nested schema, size, row count, partitioning and clustering before writing SQL.
Inputs: table_id (required), dataset_id (required), account, project_id. Returns: object
health_checkBRead-onlyIdempotent
Check local configuration without contacting Google or opening a browser. ADC is not probed.
Inputs: account. Returns: object
list_datasetsARead-onlyIdempotent
List one page of datasets in project_id or the configured default project.
Inputs: account, page_size, page_token, project_id. Returns: object
list_projectsARead-onlyIdempotent
List one page of accessible projects. First use may open Google sign-in and save a local token.
Inputs: account, page_size, page_token. Returns: object
list_tablesBRead-onlyIdempotent
List one page of tables and views within a dataset.
Inputs: dataset_id (required), account, page_size, page_token, +1 more. Returns: object
preview_tableARead-onlyIdempotent
Read a bounded page from a physical table without a SQL query job. Row order is unspecified.
Inputs: table_id (required), dataset_id (required), account, page_size, +2 more. Returns: object
run_queryA
Dry-run then submit a SELECT job that can incur Google charges. Never raises the configured byte ceiling.
Returns a job reference immediately. Use get_query_results to poll and paginate; do not resubmit to poll. project_id is the billing/job project; fully qualified SQL may read data from other accessible projects.
Inputs: sql (required), account, location, parameters, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The browse/inspect tools (list_projects, list_datasets, get_dataset, list_tables, get_table, preview_table) and the query trio (dry_run_query, run_query, get_query_results) are cleanly separated. However, health_check and connection_status both describe purely local configuration checks that never contact Google, making them near-duplicates an agent could easily pick the wrong one of. The distinction (ADC probing vs. token validity claims) is subtle and buried in long prose.
Strong verb_noun snake_case pattern throughout: list_projects, get_dataset, preview_table, dry_run_query, get_query_results. The only deviations are the two status-style names health_check and connection_status, which break the verb-first convention but remain readable and idiomatic.
Eleven tools is well within the sweet spot for a metadata-browse plus query-execution server. Each tool maps to a distinct step in the navigation/query workflow with little filler.
The explore-then-query lifecycle is well covered: projects → datasets → tables → schema/preview → dry run → execute → poll/paginate results. The notable gap is the absence of any cancellation or job-listing operation, so a runaway or expensive query has no abort path; agents can otherwise work within the read-only surface.
Maintenance
Related MCP Connectors
Provides read access to your GKE and Kubernetes resources.
Create, manage, and query your Google Cloud SQL resources.
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.
Query your own databases and Data Sets with read-only SQL, and build hosted dashboards.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables validation and dry-run analysis of BigQuery SQL queries without execution. Provides cost estimates, schema previews, and syntax validation for BigQuery queries.960 PyPI1MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only interaction with Google BigQuery, including SQL queries, dataset/table listing, schema retrieval, table preview, and metadata access via service account authentication.-
- FlicenseNot gradedqualityCmaintenanceEnables secure read-only interaction with Google BigQuery through natural language, including listing datasets, listing tables, retrieving metadata, and executing queries with cost controls.-
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to Google BigQuery, allowing users to list tables, inspect metadata, and run SELECT queries with enforced row and byte limits.Apache 2.0