MCP Reference: bigquerymigration.googleapis.com

BigQuery Migration MCP server provides tools to work with BigQuery Migration Services, such as SQL translation.

A Model Context Protocol (MCP) server 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 and set up authentication before use. For more information about using Google and Google Cloud remote MCP servers, see Google Cloud MCP servers 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. Google MCP endpoints can be global or regional.

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

https://bigquerymigration.googleapis.com/mcp

MCP Tools

An MCP tool 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 bigquerymigration.googleapis.com MCP server has the following tools:

MCP Tools
`translate_query`	Translates a single SQL query or script into BigQuery SQL. The translation runs asynchronously. Use the `get_translation` tool with the returned translation ID to poll its state until it is `SUCCEEDED` or `FAILED`. Wait at least two seconds before rechecking the state. To translate multiple queries, use the `translate_batch_queries` tool instead. A `SUCCEEDED` state means the translator finished, not that the output is correct. Check `translation_logs` before using the output. Entries with severity `ERROR` mark parts of the output that are best effort. `RelationNotFound`, `AttributeNotFound` and `MissingMetadataError` mean the translator didn't know the schema of a referenced table or column. Unresolved types can appear in the output as `ERROR_TYPE(...)` or `Error<error-type>`, which is not valid BigQuery SQL. To fix the error, provide the schema by using a metadata .ZIP file generated using the BigQuery Migration Service metadata extractor. Upload the file to Cloud Storage and pass the path to the file in `metadata_file_path`. If the user did not supply a metadata file, ask for it before guessing. Only when no metadata can be provided, use `generate_ddl_suggestion` to infer approximate DDL from the query. `NoSuchFunction` means a function the translator couldn't map was copied into the output verbatim. `UnsupportedFeatureError` or `InternalError` means a statement or clause couldn't be transpiled. Rewrite those parts manually in BigQuery SQL. The output isn't validated against BigQuery. Validate it with a BigQuery dry run before using it.
`get_translation`	Gets the SQL translation for a given translation ID. If the state is not yet `SUCCEEDED` or `FAILED`, wait at least two seconds before rechecking the state. When it is `SUCCEEDED`, check `translation_logs` for entries with severity `ERROR` before using `translated_query`. For information on what the errors mean and how to resolve them, see `translate_query`.
`explain_translation`	Explains the SQL translation for a given translation ID started by `translate_query`, what was changed between the source and the translated query, and why it was changed. Use it to understand the translation and its `WARNING` or `ERROR` logs. It doesn't change the translated query.
`generate_ddl_suggestion`	Suggests Data Definition Language (DDL) statements for an input query. For example, `CREATE TABLE` or `CREATE VIEW`. The generated DDL provides schema definitions for tables and views that are used in the query. To get DDL suggestions, call this tool, and then use the `fetch_ddl_suggestion` tool with the returned suggestion ID to poll its state until it is `SUCCEEDED` or `FAILED` and retrieve the DDL. Wait at least two seconds before rechecking the state. You can then prepend the retrieved DDL to the original input query and translate it again to improve translation quality. Use this as a fallback when no metadata .ZIP file from the source system is available. The suggested columns and types are inferred only from the columns referenced in the query or from a placeholder column when none are referenced. They are approximate and may not cover the full table schema. Prefer a metadata .ZIP file passed in `metadata_file_path` of `translate_query` for exact results. Ask the user for one before falling back to suggestions. Prepend the suggested DDL to the input query and re-translate. Then, remove the prepended DDL statements such as `CREATE TABLE` or `CREATE VIEW` from the final query keeping `SELECT ` if the inferred DDL expanded `` into partial or placeholder columns. Report the `RelationNotFound` or `AttributeNotFound` warning and the suggested DDL to the user for review.
`fetch_ddl_suggestion`	Fetches the DDL suggestion for a given suggestion ID. If the state is not yet `SUCCEEDED` or `FAILED`, wait at least two seconds before rechecking the state. The DDL is in `suggestion.suggestion_content`. For instructions on using it, see `generate_ddl_suggestion`.
`translate_batch_queries`	Translates a batch of SQL queries stored in Cloud Storage. Before calling this tool, use `gcloud storage rsync` to stage all input `.sql` files and any metadata .ZIP or YAML configuration files in Cloud Storage, and pass the path to the files in `source_base_uri`. Input `.sql` files must contain plain SQL in the source dialect. Extract SQL from your application code and replace the template or macro syntax (such as Jinja templates) with valid SQL identifiers before staging. Then, restore them after translation. If directories are reused between runs, wipe `target_base_uri` first so that outputs of a previous run are not mixed with the new ones. The translation runs asynchronously. Use the `fetch_batch_translation` tool with the returned translation ID to poll its state until it is `SUCCEEDED` or `FAILED`. Wait at least 10 seconds before rechecking the state.
`fetch_batch_translation`	Retrieves a batch translation workflow's state and logs. If the state is not yet `SUCCEEDED` or `FAILED`, wait at least 10 seconds before rechecking the state. When it has finished, use `gcloud storage rsync` to download the outputs from `target_base_uri`, including translated files under `sql/` and the full log report at `report/translation_report.csv`. Review `translation_logs` and `report/translation_report.csv` for entries with severity `ERROR`, which indicate files where the translation failed or is best effort. `RelationNotFound` and `AttributeNotFound` mean the schema of a referenced table or column was missing. Provide a metadata .ZIP file generated with the BigQuery Migration Service metadata extractor or ask the user for one if none was supplied. You can also use `generate_batch_ddl_suggestion` when no metadata can be provided. For `SyntaxError`, `NoSuchFunction`, `UnsupportedFeatureError`, or `InternalError`, fix the invalid input or manually rewrite the unmapped functions and untranslated statements in the output. Then, validate with a BigQuery dry run.
`generate_batch_ddl_suggestion`	Generates Data Definition Language (DDL) suggestions for a batch of queries stored in Cloud Storage. This is a fallback for when no metadata .ZIP file is available from the source system. The suggested columns and types are inferred only from the columns referenced in the queries or from a placeholder column when none are referenced. They are approximate and may not cover the full table schema. The suggestion runs asynchronously. Use the `fetch_batch_ddl_suggestion` tool with the returned suggestion ID to poll its state until it is `SUCCEEDED` or `FAILED`. Wait at least 10 seconds before rechecking the state.
`fetch_batch_ddl_suggestion`	Retrieves a batch DDL suggestion workflow's state and logs. If the state is not yet `SUCCEEDED` or `FAILED`, wait at least 10 seconds before rechecking the state. When it has finished, download the generated DDL from `suggestion.cloud_storage_uri`, and ask the user to review it. If the user accepts it, upload it as plain `.sql` files into a directory under `source_base_uri`. Don't zip the files. `.zip` is reserved for metadata extractor output. After uploading the files run `translate_batch_queries` again. In the translated output, keep `SELECT ` if the inferred DDL expanded `` into partial or placeholder columns.
`translate_metadata`	Translates a metadata .ZIP file into Data Definition Language (DDL) statements and table mappings that are written to `target_base_uri`. The metadata file is generated by the BigQuery Migration Service metadata extractor and should be uploaded to Cloud Storage. The translation runs asynchronously. Use the `fetch_batch_translation` tool with the returned translation ID to poll its state until it is `SUCCEEDED` or `FAILED`. Wait at least 10 seconds before rechecking the state. If it fails, read the logs returned by `fetch_batch_translation` to diagnose the issue. After it succeeds, read the results from `target_base_uri`.

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
curl --location 'https://bigquerymigration.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }'

Curl Request

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

MCP Reference: bigquerymigration.googleapis.com Stay organized with collections Save and categorize content based on your preferences.