Merge Unified's Google BigQuery integration Merge Agent Handler's Google BigQuery MCP server

Connect your AI Agents to Google BigQuery in minutes

Merge lets you securely connect your agents to Google BigQuery and thousands of tools instantly

Start building for free

Read docs

Google BigQuery

Learn more about Merge Agent Handler

Available tools

list_datasets

List datasets in a BigQuery project. Returns dataset IDs, descriptions, and locations. Use list_projects first to get available project IDs.

get_dataset

Get detailed information about a specific BigQuery dataset including description, location, labels, and access controls. Use list_datasets to find available dataset IDs.

create_dataset

Create a new dataset in a BigQuery project. Specify location (US, EU, etc.) at creation time — it cannot be changed later. Use list_projects to find available project IDs.

update_dataset

Update a BigQuery dataset's description, friendly name, labels, or default table expiration. Location cannot be changed. Use list_datasets to find available dataset IDs.

delete_dataset

Delete a BigQuery dataset. Set deletecontents=true to delete all tables in the dataset. Without it, the dataset must be empty. Use listdatasets to find available dataset IDs.

list_jobs

List BigQuery jobs in a project. Filter by state (done, pending, running) and projection level. Returns job IDs, types, status, and statistics.

get_job

Get detailed information about a specific BigQuery job including status, configuration, and statistics. Use listjobs to find job IDs, or use the jobid from a run_query response.

cancel_job

Cancel a running BigQuery job. The job may still complete if it finishes before the cancellation takes effect. Use listjobs with statefilter='running' to find cancellable jobs.

list_projects

List all BigQuery projects accessible to the authenticated user. Returns project IDs, names, and numeric IDs. Use this to discover available projects before querying datasets or tables.

run_query

Execute a SQL query in BigQuery and return results. Supports GoogleSQL (default) and legacy SQL. If the query doesn't complete within timeout, use getqueryresults with the returned job_id to poll for results.

get_query_results

Get results from a previously executed query using its job ID. Use this to poll for long-running query completion or to paginate through large result sets. The jobid comes from a previous runquery response.

list_tables

List tables in a BigQuery dataset. Returns table IDs, types, and creation times. Use list_datasets first to get available dataset IDs.

get_table

Get detailed information about a BigQuery table including schema, row count, size, and partitioning config. Use list_tables to find available table IDs.

create_table

Create a new table in a BigQuery dataset with a typed schema. Supports STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, RECORD, and more. Use list_datasets to find available dataset IDs.

update_table

Update a BigQuery table's description, friendly name, labels, or schema (add new columns only — cannot remove/rename). Use list_tables to find available table IDs.

delete_table

Delete a BigQuery table permanently. This cannot be undone. Use list_tables to find available table IDs.

list_table_data

Read rows from a BigQuery table. Returns data as column:value dicts with pagination support. For filtered/aggregated data, use runquery instead. Use listtables to find table IDs.

insert_table_data

Stream-insert rows into a BigQuery table. Each row is a dict of columnname:value pairs. Returns insert errors if any rows fail. Use listtables to find table IDs.

copy_table

Copy a BigQuery table to a new location (within/across datasets or projects). This is an async operation that returns a job ID — use getjob to poll for completion. Source and destination datasets must be in the same location. Use listtables to find available table IDs.

export_table_to_gcs

Export a BigQuery table to Google Cloud Storage in CSV, JSON, Avro, or Parquet format. This is an async operation — use getjob to poll for completion. For tables >1GB, use wildcard in URI (gs://bucket/file-*.csv). CSV does not support nested data — use JSON, Avro, or Parquet instead. Use listtables to find available table IDs.

validate_credential

Validate Google BigQuery credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Google BigQuery MCP server

What is a Google BigQuery MCP?

It's an MCP server that connects your agents directly to Google BigQuery's cloud data warehouse via tools. Your agents can invoke these tools to run SQL queries, explore dataset schemas, retrieve table metadata, list available resources, and more.

Google offers an official BigQuery MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Google BigQuery MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

On-demand analytics from conversational agents: When a user asks a business question in a chat interface, an agent translates it into SQL, runs the query against BigQuery, and returns a formatted summary with key numbers and trends without requiring the user to open a BI tool

Pipeline validation after ETL jobs: After a data pipeline completes, an agent queries BigQuery to verify row counts, check for nulls in required fields, and flag anomalies before downstream reports or dashboards are generated

Scheduled business metric reporting: On a daily or weekly schedule, an agent runs a set of predefined SQL queries against BigQuery, formats the results into a readable digest, and posts them to the relevant Slack channel or sends them as an email summary

Schema discovery for data onboarding: When a new dataset is added to a project, an agent lists the available tables, retrieves schema details for each, and assembles a data dictionary document in Notion or Google Docs for the analytics team

What are popular tools for Google BigQuery's MCP server?

Here are some of the most commonly used tools:

execute_sql: runs a SQL statement against BigQuery with read-write access, supporting DML and DDL operations. Use this when an agent needs to insert, update, or transform data as part of an automated pipeline or data preparation workflow

execute_sql_readonly: runs a read-only SQL query against BigQuery, blocking any mutations. Good for analytics agents that need to query and report on data without any risk of modifying underlying tables

list_dataset_ids: returns the dataset IDs available in a BigQuery project. Call this when an agent needs to discover what data is available before running queries or building a schema map for a new workflow

list_table_ids: lists the tables within a specified BigQuery dataset. Helpful when an agent is navigating a dataset's structure to identify the right table before querying or performing schema validation

get_dataset_info: retrieves metadata for a specific BigQuery dataset, including location, creation time, and access configuration. Use this when an agent needs to confirm dataset properties before executing operations against it

get_table_info: returns detailed information about a table, including its schema, row count, and partitioning settings. Useful for agents building dynamic queries or verifying that a table's structure matches an expected format before processing

What makes Merge Agent Handler's Google BigQuery MCP server better than alternative Google BigQuery MCP servers?

Google has an official BigQuery MCP server, but running it through Merge Agent Handler adds enterprise controls that matter when agents are touching production data:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For BigQuery, this means you can prevent raw query results, table contents, and schema details from being surfaced to agents that don't need full access to the underlying data

Managed authentication and credentials: Merge stores and manages your BigQuery OAuth credentials on your behalf. You never inject service account keys or tokens into agent configuration, and you don't need to handle re-authorization as credentials rotate

Real-time observability and audit trail: Every tool call against BigQuery is logged: which query ran, which dataset or table was targeted, and what the response contained. Data and security teams can audit exactly what an agent read or wrote without any custom instrumentation

Tool Packs and controlled access: Tool Packs let you bundle specific BigQuery tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Google BigQuery MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Google BigQuery connector. Match the tools to your use case: executesql_readonly and the list and get_ tools are enough for reporting and discovery agents, while execute_sql is needed for agents that write or transform data.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Google BigQuery by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Google BigQuery tools are now accessible through that endpoint.