MCP Reference: cloud-sql

Model Context Protocol (MCP) 服务器充当外部服务（为大语言模型 [LLM] 或 AI 应用提供上下文、数据或功能）与 LLM 或 AI 应用之间的代理。MCP 服务器将 AI 应用连接到数据库和 Web 服务等外部系统，并将这些系统的响应转换为 AI 应用可理解的格式。

服务器设置

您必须先启用 MCP 服务器并设置身份验证，然后才能使用。如需详细了解如何使用 Google 和 Google Cloud 远程 MCP 服务器，请参阅 Google Cloud MCP servers overview。

适用于 MCP 的 Cloud SQL Admin API

服务器端点

MCP 服务端点是 MCP 服务器的网络地址和通信接口（通常是网址），AI 应用（MCP 客户端的宿主）使用该端点来建立安全、标准化的连接。它是 LLM 请求上下文、调用工具或访问资源的交互点。Google MCP 端点可以是全球性的，也可以是区域性的。

cloud-sql MCP 服务器具有以下 MCP 端点：

  • https://sqladmin.googleapis.com/mcp

MCP 工具

MCP 工具是 MCP 服务器向 LLM 或 AI 应用公开的函数或可执行功能，用于在现实世界中执行操作。

cloud-sql MCP 服务器具有以下工具：

MCP 工具
list_instances 列出项目中的所有 Cloud SQL 实例。
get_instance 获取 Cloud SQL 实例的详细信息。
create_instance

启动 Cloud SQL 实例的创建。

  • 该工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
  • 实例创建操作可能需要几分钟的时间。使用命令行工具暂停 30 秒，然后再重新检查状态。
  • 使用 create_instance 工具创建实例后，您可以使用 create_user 工具为当前登录到项目的用户创建 IAM 用户账号。
  • 重要提示：如果创建 Private Service Connect 或 Private Service Access 实例，请将 ipv4_enabled 设置为“false”。

  • data_api_access 的值默认设置为 ALLOW_DATA_API。借助此设置，您可以使用 execute_sql 工具和 executeSql API 执行 SQL 语句。

除非另有说明，否则新创建的实例将使用开发环境的默认实例配置。

以下是开发环境中实例的默认配置：

{
  "tier": "db-perf-optimized-N-2",
  "data_disk_size_gb": 100,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "ZONAL",
  "tags": [{"environment": "dev"}]
}

建议将以下配置用于生产环境中的实例：

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}

建议将以下实例配置用于 SQL Server：

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "SQLSERVER_2022_STANDARD",
  "edition": "ENTERPRISE",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}
execute_sql

在 Cloud SQL 实例上执行任何有效的 SQL 语句，包括数据定义语言 (DDL)、数据控制语言 (DCL)、数据查询语言 (DQL) 或数据操纵语言 (DML) 语句。

如需支持 execute_sql 工具，Cloud SQL 实例必须满足以下要求：

  • data_api_access 的值必须设置为 ALLOW_DATA_API。
  • 对于内置用户，必须设置 password_secret_version。
  • 否则，对于 IAM 用户，对于 MySQL 实例，数据库标志 cloudsql_iam_authentication 必须设置为 on。对于 PostgreSQL 实例，数据库标志 cloudsql.iam_authentication 必须设置为 on。
  • 使用 create_instance 工具创建实例后，您可以使用 create_user 工具为当前登录到项目的用户创建 IAM 用户账号。

execute_sql 工具具有以下限制：

  • 如果 SQL 语句返回的响应大于 10 MB，则该响应将被截断。
  • execute_sql 工具的默认超时时间为 30 秒。如果查询运行时间超过 30 秒，则该工具会返回 DEADLINE_EXCEEDED 错误。
  • SQL Server 不支持 execute_sql 工具。

如果您收到类似于“IAM authentication is not enabled for the instance”（未为此实例启用 IAM 身份验证）的错误，则可以使用 get_instance 工具检查该实例的 IAM 数据库身份验证标志的值。

如果您收到类似于“The instance doesn't allow using executeSql to access this instance”（此实例不允许使用 executeSql 访问此实例）的错误，则可以使用 get_instance 工具检查 data_api_access 设置。

当您收到身份验证错误时：

  1. 使用 list_users 工具检查当前登录的用户账号是否作为 IAM 用户存在于实例中。
  2. 如果 IAM 用户账号不存在，请使用 create_user 工具为登录用户创建 IAM 用户账号。
  3. 如果当前登录的用户没有适当的数据库用户角色，则可以使用 update_user 工具向用户授予数据库角色。例如，cloudsqlsuperuser 角色可以为 IAM 用户提供许多必需的权限。

  4. 检查当前登录的用户是否已为项目分配正确的 IAM 权限。您可以使用 gcloud projects get-iam-policy [PROJECT_ID] 命令检查用户是否已为项目分配适当的 IAM 角色或权限。

    • 用户必须具有 cloudsql.instance.login 权限才能执行自动 IAM 数据库身份验证。
    • 用户必须具有 cloudsql.instances.executeSql 权限才能使用 execute_sql 工具或 executeSql API 执行 SQL 语句。
    • 包含所需权限的常见 IAM 角色：Cloud SQL 实例用户 (roles/cloudsql.instanceUser) 或 Cloud SQL 管理员 (roles/cloudsql.admin)

收到 ExecuteSqlResponse 时，请务必检查响应正文中的 message 和 status 字段。成功的 HTTP 状态代码并不能保证所有 SQL 语句都完全成功。message 和 status 字段将指示在执行 SQL 语句期间是否存在任何部分错误或警告。
execute_sql_readonly

在 Cloud SQL 实例上执行任何有效的只读 SQL 语句。

如需支持 execute_sql_readonly 工具，Cloud SQL 实例必须满足以下要求：

  • data_api_access 的值必须设置为 ALLOW_DATA_API。
  • 对于 MySQL 实例，数据库标志 cloudsql_iam_authentication 必须设置为 on。对于 PostgreSQL 实例，数据库标志 cloudsql.iam_authentication 必须设置为 on。
  • 调用 execute_sql_readonly 工具需要 IAM 用户账号或 IAM 服务帐号（CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT）。该工具使用通过 IAM 数据库身份验证登录的数据库用户的权限执行 SQL 语句。

使用 create_instance 工具创建实例后，您可以使用 create_user 工具为当前登录到项目的用户创建 IAM 用户账号。

execute_sql_readonly 工具具有以下限制：

  • 如果 SQL 语句返回的响应大于 10 MB，则该响应将被截断。
  • 该工具的默认超时时间为 30 秒。 如果查询运行时间超过 30 秒，则该工具会返回 DEADLINE_EXCEEDED 错误。
  • SQL Server 不支持该工具。

如果您收到类似于“IAM authentication is not enabled for the instance”（未为此实例启用 IAM 身份验证）的错误，则可以使用 get_instance 工具检查该实例的 IAM 数据库身份验证标志的值。

如果您收到类似于“The instance doesn't allow using executeSql to access this instance”（此实例不允许使用 executeSql 访问此实例）的错误，则可以使用 get_instance 工具检查 data_api_access 设置。

当您收到身份验证错误时：

  1. 使用 list_users 工具检查当前登录的用户账号是否作为 IAM 用户存在于实例中。
  2. 如果 IAM 用户账号不存在，请使用 create_user 工具为登录用户创建 IAM 用户账号。
  3. 如果当前登录的用户没有适当的数据库用户角色，则可以使用 update_user 工具向用户授予数据库角色。例如，cloudsqlsuperuser 角色可以为 IAM 用户提供许多必需的权限。

  4. 检查当前登录的用户是否已为项目分配正确的 IAM 权限。您可以使用 gcloud projects get-iam-policy [PROJECT_ID] 命令检查用户是否已为项目分配适当的 IAM 角色或权限。

    • 用户必须具有 cloudsql.instance.login 权限才能执行自动 IAM 数据库身份验证。
    • 用户必须具有 cloudsql.instances.executeSql 权限才能使用 execute_sql_readonly 工具或 executeSql API 执行 SQL 语句。
    • 包含所需权限的常见 IAM 角色：Cloud SQL 实例用户 (roles/cloudsql.instanceUser) 或 Cloud SQL 管理员 (roles/cloudsql.admin)

收到 ExecuteSqlResponse 时，请务必检查响应正文中的 message 和 status 字段。成功的 HTTP 状态代码并不能保证所有 SQL 语句都完全成功。message 和 status 字段将指示在执行 SQL 语句期间是否存在任何部分错误或警告。
get_operation 获取长时间运行的操作的状态。长时间运行的操作可能需要几分钟才能完成。如果操作需要很长时间，请使用命令行工具暂停 30 秒，然后再重新检查操作的状态。
create_user

为 Cloud SQL 实例创建数据库用户。

  • 该工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
  • 使用 create_user 工具时，请指定用户类型： CLOUD_IAM_USER、CLOUD_IAM_SERVICE_ACCOUNT 或 BUILT_IN。
  • 默认情况下，新创建的用户会被分配 cloudsqlsuperuser 角色，除非您在请求中明确指定其他数据库角色。
  • 如果用户是当前登录的 IAM 用户，则可以使用 execute_sql 工具使用新创建的用户。execute_sql 工具使用通过 IAM 数据库身份验证登录的数据库用户的权限执行 SQL 语句。

create_user 工具具有以下限制：

  • 如需创建带密码的内置用户，请使用 password_secret_version 字段通过 Google Cloud Secret Manager 提供密码。password_secret_version 的值应为密钥版本的资源名称，例如 projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 或 projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest。调用方需要对密钥版本具有 secretmanager.secretVersions.access 权限。
  • create_user 工具不支持为 SQL Server 创建用户。

如需在 PostgreSQL 中创建 IAM 用户，请执行以下操作：

  • 数据库用户名必须是 IAM 用户的电子邮件地址，且必须全部为小写。 例如，如需为 PostgreSQL IAM 用户 example-user@example.com 创建用户，可以使用以下请求：
{
  "name": "example-user@example.com",
  "type": "CLOUD_IAM_USER",
  "instance":"test-instance",
  "project": "test-project"
}

为 IAM 用户创建的数据库用户名为 example-user@example.com。

如需在 PostgreSQL 中创建 IAM 服务帐号，请执行以下操作：

  • 即使账号的完整电子邮件地址为service-account-name@project-id.iam.gserviceaccount.com，也必须在创建数据库用户名时不使用.gserviceaccount.com后缀。例如，如需为 PostgreSQL 创建 IAM 服务帐号，可以使用以下请求格式：
{
   "name": "test@test-project.iam",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

为 IAM 服务帐号创建的数据库用户名为 test@test-project.iam。

如需在 MySQL 中创建 IAM 用户或 IAM 服务帐号，请执行以下操作：

  • 当 Cloud SQL for MySQL 存储用户名时，它会从用户或服务帐号的电子邮件地址中截断 @ 和域名。例如，example-user@example.com 会变为 example-user。
  • 因此，您不能将具有相同用户名但不同域名的两个 IAM 用户或服务账号添加到同一 Cloud SQL 实例。
  • 例如，如需为 MySQL IAM 用户 example-user@example.com 创建用户，请使用以下请求：
{
   "name": "example-user@example.com",
   "type": "CLOUD_IAM_USER",
   "instance": "test-instance",
   "project": "test-project"
}

为 IAM 用户创建的数据库用户名为 example-user。

  • 例如，如需创建 MySQL IAM 服务帐号 service-account-name@project-id.iam.gserviceaccount.com，请使用以下请求：
{
   "name": "service-account-name@project-id.iam.gserviceaccount.com",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

为 IAM 服务帐号创建的数据库用户名为 service-account-name。
update_user

更新 Cloud SQL 实例的数据库用户。update_user 的常见用例是向用户授予 cloudsqlsuperuser 角色，该角色可以为用户提供许多必需的权限。

此工具仅支持更新用户以分配数据库角色。

  • 该工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
  • 在调用 update_user 工具之前，请务必使用 list_users 工具检查用户的现有配置，例如用户类型。
  • 对于 MySQL 的特殊情况，如果 list_users 工具为 iamEmail 字段返回完整的电子邮件地址（例如 {name=test-account, iamEmail=test-account@project-id.iam.gserviceaccount.com}），则在您的 update_user 请求中，请在工具请求的 name 字段中使用 iamEmail 字段中的完整电子邮件地址。例如，name=test-account@project-id.iam.gserviceaccount.com。

更新用户角色的关键参数：

  • database_roles：要分配给用户的数据库角色列表。
  • revokeExistingRoles：一个布尔值字段（默认值：false），用于控制如何处理现有角色。

角色更新的工作原理：

  1. 如果 revokeExistingRoles 为 true：

    • 系统将撤消授予用户但不在提供的 database_roles 列表中的任何现有角色。
    • 撤消仅适用于非系统角色。系统角色（例如 cloudsqliamuser 等）不会被撤消。
    • 系统将授予用户尚未拥有的 database_roles 列表中的任何角色。
    • 如果 database_roles 为空，则系统会撤消所有现有的非系统角色。

  2. 如果 revokeExistingRoles 为 false（默认值）：

    • 系统将授予用户尚未拥有的 database_roles 列表中的任何角色。
    • 系统将保留不在 database_roles 列表中的现有角色。
    • 如果 database_roles 为空，则用户的角色不会发生任何变化。

示例：

  • 现有角色：[roleA, roleB]

    • 请求：database_roles: [roleB, roleC], revokeExistingRoles: true
    • 结果：撤消 roleA，授予 roleC。用户角色变为 [roleB, roleC]。
    • 请求：database_roles: [roleB, roleC], revokeExistingRoles: false
    • 结果：授予 roleC。用户角色变为 [roleA, roleB, roleC]。
    • 请求：database_roles: [], revokeExistingRoles: true
    • 结果：撤消 roleA，撤消 roleB。用户角色变为 []。
    • 请求：database_roles: [], revokeExistingRoles: false
    • 结果：无变化。用户角色仍为 [roleA, roleB]。
clone_instance

创建 Cloud SQL 实例作为源实例的克隆。

  • 该工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
  • 克隆操作可能需要几分钟的时间。使用命令行工具暂停 30 秒，然后再重新检查状态。
update_instance

部分更新 Cloud SQL 实例的配置设置。

  • 该工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
  • 某些更新操作（例如更改版本升级或实例层级等）可能会导致实例重启，从而导致停机。在继续执行此类操作之前，请先获得用户的确认。
list_users 列出 Cloud SQL 实例的所有数据库用户。
create_backup 在 Cloud SQL 实例上执行备份。请务必在请求中填充项目和实例字段。您还可以选择性地提供备份的位置（区域）和说明，在这种情况下，还应填充相应的请求字段。
restore_backup

将备份恢复到 Cloud SQL 实例。

必须在请求中提供并填充 target_instance 和 target_project。

您可以通过多种方式提供备份标识符：

  1. backup_run_id（一个整数）。
  2. 格式为 projects/{project-id}/backups/{backup-uid} 的备份 URI。
  3. 格式为 projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid} 的备份 URI。

使用标识符填充请求中的 backup_id 字段。

必须在请求中填充 source_project。如果标识符是 backup_run_id，则系统将提供 source_project。如果标识符是备份 URI，则可能需要从 URI 中提取 source_project。请勿将提取的 source_project 与 target_project 混淆，后者将以其他方式提供。

此外，如果标识符是 backup_run_id，则必须在请求中提供并填充 source_instance。

请勿在恢复之前尝试创建实例，恢复本身会在需要时创建实例。

在执行恢复之前，请先向用户确认参数。
import_data

将数据导入 Cloud SQL 实例。

如果文件不是以 gs:// 开头，则假定该文件存储在本地。如果文件是本地文件，则必须先将该文件上传到 Cloud Storage，然后才能进行实际的 import_data 调用。如需将文件上传到 Cloud Storage，可以使用 gcloud 或 gsutil 命令。

在将文件上传到 Cloud Storage 之前，请考虑是否要在提供的项目中创建新存储桶或使用现有存储桶。

将文件上传到 Cloud Storage 后，实例服务帐号必须具有足够的权限才能从 Cloud Storage 存储桶读取上传的文件。

这可以通过以下方式实现：

  1. 使用 get_instance 工具获取实例服务帐号的电子邮件地址。 从该工具的输出中，获取 serviceAccountEmailAddress 字段的值。
  2. 在提供的 Cloud Storage 存储桶中，向实例服务帐号授予 storage.objectAdmin 角色。使用 gcloud storage buckets add-iam-policy-binding 等命令或向 Cloud Storage API 发出请求。授予角色并将权限传播到 Cloud Storage 中的服务帐号可能需要 2 到 7 分钟或更长时间。如果在更新 IAM 政策后遇到权限错误，请等待几分钟，然后重试。

授予权限后，您就可以导入数据了。我们建议您将可选参数留空，并使用系统默认值。文件类型通常可以根据文件扩展名确定。例如，如果文件是 SQL 文件，则为 .sql；如果是 CSV 文件，则为 .csv。

以下是 MySQL 的示例 SQL importContext。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL"
}

MySQL 没有 database 参数，因为数据库名称应存在于 SQL 文件中。只能指定一个 URI。除了 importContext 之外，不需要其他字段。

对于 PostgreSQL，database 字段是必需的。以下是指定了 database 字段的示例 PostgreSQL importContext。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL",
  "database": "sample-db"
}

import_data 工具会返回一个长时间运行的操作。使用 get_operation 工具轮询其状态，直到操作完成。
postgres_upgrade_precheck

检查 Cloud SQL for PostgreSQL 实例是否已准备好进行主要版本升级到指定目标版本。

必须在请求中提供 target_database_version（例如 POSTGRES_15）。

此工具可帮助您在尝试实际升级之前发现潜在问题，从而降低失败或停机的风险。

此工具仅支持 PostgreSQL 主实例，并且不会在读取副本上运行。

预检通常会评估：

  • 数据库架构与目标版本的兼容性。
  • Cloud SQL 限制和不受支持的功能。
  • 实例资源限制（例如关系数）。
  • 当前数据库设置和扩展程序的兼容性。
  • 实例的整体运行状况和准备情况。

该工具会返回一个长时间运行的操作。使用此调用返回的操作名称和 get_operation 工具轮询其状态。

重要提示：操作状态为 DONE 后，详细的预检结果将显示在 Operation 资源中。您需要检查 get_operation 的响应。结果位于 pre_check_major_version_upgrade_context.pre_check_response 字段中。

结果采用结构化形式，表示：

  • INFO：一般信息。
  • WARNING：不会阻碍升级但应检查的潜在问题。
  • ERROR：必须在尝试升级之前解决的严重问题。

每项发现结果都应包含一条消息和任何必需的操作。在继续进行主要版本升级之前，解决所有报告的问题至关重要。如果 pre_check_response 为空或缺失，则表示预检期间未发现任何问题。

运行此预检不会影响实例的可用性。

获取 MCP 工具规范

如需获取 MCP 服务器中所有工具的 MCP 工具规范，请使用 tools/list 方法。下面的示例演示了如何使用 curl 列出 MCP 服务器中当前可用的所有工具及其规范。

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