BigQuery Migration MCP server provides tools to work with BigQuery Migration Services, such as [SQL translation](https://docs.cloud.google.com/bigquery/docs/api-sql-translator.md.txt).

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.md.txt) and [set up authentication](https://docs.cloud.google.com/mcp/authenticate-mcp.md.txt) 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.md.txt).

### 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 Migration API MCP server has the following global MCP endpoint:

- https://bigquerymigration.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 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`. |
| `trace_lineage` | Traces the data lineage of a source data warehouse from its query logs and metadata. Before calling this tool, extract metadata and query logs from the source system as .ZIP files using `gcloud alpha bq migration metadata extract` and `gcloud alpha bq migration query-logs extract`. Then, upload the files to a Cloud Storage folder using `gcloud storage rsync`, and pass the folder in `source_base_uri`. Supported source systems are Teradata, Redshift, Snowflake, and BigQuery. The lineage service processes the first 5 GB of the oldest query logs. Tracing runs asynchronously and can take several hours for large inputs. Use the `get_lineage` tool with the lineage ID returned in `name` to poll its state until it is `SUCCEEDED` or `FAILED`. Wait at least 30 seconds before rechecking the state. |

### 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://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 }' ``` |