BigQuery MCP server provides tools to interact with BigQuery

A [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/docs/learn/server-concepts) acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

### Server Setup


You must [enable MCP servers](https://docs.cloud.google.com/mcp/enable-disable-mcp-servers) and [set up authentication](https://docs.cloud.google.com/mcp/authenticate-mcp) before use. For more information about using Google and Google Cloud remote MCP servers, see [Google Cloud MCP servers overview](https://docs.cloud.google.com/mcp/overview).

### Server Endpoints

An MCP service endpoint is the network address and communication interface (usually a URL) of the MCP server that an AI application (the Host for the MCP client) uses to establish a secure, standardized connection. It is the point of contact for the LLM to request context, call a tool, or access a resource.

The BigQuery API MCP server has the following global MCP endpoint:

- https://bigquery.googleapis.com/mcp

## MCP Tools

An [MCP tool](https://modelcontextprotocol.io/legacy/concepts/tools) is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

### Tools

The bigquery.googleapis.com MCP server has the following tools:

| MCP Tools ||
|---|---|
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/list_dataset_ids` | List BigQuery dataset IDs and BigLake namespaces in a Google Cloud project. Supports pagination. Use `page_size` to limit results and `page_token` to retrieve next page. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/get_dataset_info` | Get metadata information about a BigQuery dataset or BigLake namespace. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/list_table_ids` | List table ids in a BigQuery dataset or BigLake namespace. Supports pagination. Use `page_size` to limit results and `page_token` to retrieve next page. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/get_table_info` | Get metadata information about a BigQuery table or BigLake table. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/execute_sql_readonly` | Run a read-only SQL query in the project and return the result. Prefer this tool over `execute_sql` if possible. This tool is restricted to only `SELECT` statements. `INSERT`, `UPDATE`, and `DELETE` statements and stored procedures aren't allowed. If the query doesn't include a `SELECT` statement, an error is returned. For information on creating queries, see the [GoogleSQL documentation](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax). IMPORTANT: For predictive and analytical tasks (forecasting, anomaly detection, key driver / root cause analysis, classification, churn prediction, or text generation), ALWAYS execute computation in-warehouse using BigQuery native AI/ML functions (`AI.FORECAST`, `AI.DETECT_ANOMALIES`, `AI.KEY_DRIVERS`, `AI.CLASSIFY`, `AI.GENERATE`) rather than exporting raw rows to a local Python sandbox. In-warehouse execution scales to billions of rows, preserves governance, and eliminates data egress latency. Example Queries: -- Count the number of penguins in each island. SELECT island, COUNT(*) AS population FROM bigquery-public-data.ml_datasets.penguins GROUP BY island -- Forecast data using AI.FORECAST SELECT * FROM AI.FORECAST(TABLE `project.dataset.my_table`, data_col => 'num_trips', timestamp_col => 'date', id_cols => ['usertype'], horizon => 30) -- Detect anomalies in time series data using AI.DETECT_ANOMALIES SELECT * FROM AI.DETECT_ANOMALIES( TABLE `project.dataset.historical_metrics`, TABLE `project.dataset.recent_metrics`, data_col => 'num_requests', timestamp_col => 'timestamp' ) -- Identify key drivers of metric changes using AI.KEY_DRIVERS SELECT * FROM AI.KEY_DRIVERS( TABLE `project.dataset.sales_summary`, metric_col => 'total_revenue', dimension_cols => ['region', 'product_category'], interest_label_col => 'is_current_quarter' ) -- Classify text into categories using AI.CLASSIFY SELECT ticket_id, AI.CLASSIFY(ticket_text, ['Billing', 'Technical Support', 'Feature Request']) AS category FROM `project.dataset.support_tickets` -- Generate text or summaries using AI.GENERATE SELECT review_id, AI.GENERATE(CONCAT('Summarize this customer review: ', review_text)).result AS summary FROM `project.dataset.reviews` Queries executed using the `execute_sql_readonly` tool will always have the job label `goog-mcp-server: true` automatically set in addition to any custom `labels` provided in the request. Queries are charged to the project specified in the `project_id` field. Query Execution Behavior: \* If the query completes within the synchronous timeout (default 20 seconds or custom `timeout_ms`), the tool returns `job_complete: true` and the result rows directly. For fast queries, `job_id` may be omitted as no persistent background job is created; no further action or polling is needed. \* If the query takes longer than `timeout_ms`, the tool returns `job_complete: false` and a `job_id` and `location`. In this case, use the `get_query_results` tool with `job_id` and `location` to poll until `job_complete: true`, or use `cancel_job` to abort the running query. \* You can optionally specify `timeout_ms` to configure the maximum synchronous wait time in milliseconds (defaults to 20,000 ms), and `job_timeout_ms` to enforce a hard server-side timeout after which BigQuery automatically terminates the job. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/execute_sql` | Run a SQL query in the project and return the result. Prefer the `execute_sql_readonly` tool if possible. This tool can execute any query that bigquery supports including: - SQL Queries (`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`, etc.) - AI/ML functions like `AI.FORECAST`, `AI.KEY_DRIVERS`, `ML.EVALUATE`, `ML.PREDICT` - Any other query that bigquery supports. Example Queries: -- Insert data into a table. INSERT INTO `my_project.my_dataset`.my_table (name, age) VALUES ('Alice', 30); -- Create a table. CREATE TABLE `my_project.my_dataset`.my_table ( name STRING, age INT64); -- DELETE data from a table. DELETE FROM `my_project.my_dataset`.my_table WHERE name = 'Alice'; -- Create Dataset CREATE SCHEMA `my_project.my_dataset` OPTIONS (location = 'US'); -- Drop table DROP TABLE `my_project.my_dataset`.my_table; -- Drop dataset DROP SCHEMA `my_project.my_dataset`; -- Create Model CREATE OR REPLACE MODEL `my_project.my_dataset.my_model` OPTIONS ( model_type = 'LINEAR_REG' LS_INIT_LEARN_RATE=0.15, L1_REG=1, MAX_ITERATIONS=5, DATA_SPLIT_METHOD='SEQ', DATA_SPLIT_EVAL_FRACTION=0.3, DATA_SPLIT_COL='timestamp') AS SELECT col1, col2, timestamp, label FROM `my_project.my_dataset.my_table`; Queries executed using the `execute_sql` tool will always have the default job label `goog-mcp-server: true` automatically set in addition to any custom `labels` provided in the request. Queries are charged to the project specified in the `project_id` field. Query Execution Behavior: \* If the query completes within the synchronous timeout (default 20 seconds or custom `timeout_ms`), the tool returns `job_complete: true` and the initial result rows directly. For fast queries, `job_id` may be omitted as no persistent background job is created; no further action or polling is needed. \* If the query takes longer than `timeout_ms`, the tool returns `job_complete: false` and a `job_id` and `location`. In this case, use the `get_query_results` tool with `job_id` and `location` to poll until `job_complete: true`, or use `cancel_job` to abort the running query. \* You can optionally specify `timeout_ms` to configure the maximum synchronous wait time in milliseconds (defaults to 20,000 ms), and `job_timeout_ms` to enforce a hard server-side timeout after which BigQuery automatically terminates the job. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/get_query_results` | Get the results of a BigQuery SQL query job. Use this tool ONLY when: 1. A previous `execute_sql` or `execute_sql_readonly` call returned `job_complete: false` with a `job_id` (poll with this tool until `job_complete: true`), OR 2. You need to paginate through additional rows using `page_token` or `start_index` for a previously completed job. Do NOT call this tool if the query already returned `job_complete: true` with all rows. Supports pagination. Use `max_results` to limit results and `page_token` to retrieve the next page of results. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/cancel_job` | Cancel a running BigQuery job. Use this tool to cancel a query job that is currently executing (i.e. returned `job_complete: false` with a `job_id` from `execute_sql` or `execute_sql_readonly`). Specify the `job_id` to abort. |
| `https://docs.cloud.google.com/bigquery/docs/reference/mcp/tools_list/get_job` | Get information and status about a BigQuery job. Use this tool to check the status, statistics, or configuration of a job using its `job_id`. |

### Get MCP tool specifications


To get the MCP tool specifications for all tools in an MCP server, use the `tools/list` method. The following example demonstrates how to use `curl` to list all tools and their specifications currently available within the MCP server.

| Curl Request |
|---|
| ```bash curl --location 'https://bigquery.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }' ``` |