MCP Tools Reference: bigquery.googleapis.com

Tool: `execute_sql`

Run a SQL query in the project and return the result.

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.

The execute_sql tool can also have side effects if the the query invokes remote functions or Python UDFs.

All queries that are run using the execute_sql tool have a label that identifies the tool as the source. You can use this label to filter the queries using the label and value pair goog-mcp-server: true.

Queries are charged to the project specified in the project_id field.

The following sample demonstrate how to use curl to invoke the execute_sql MCP tool.

Curl Request
curl --location 'https://bigquery.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "execute_sql", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }'

Curl Request

                  
curl --location 'https://bigquery.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout.

JSON representation
{ "projectId": string, "query": string, "dryRun": boolean }

Fields

Fields
`projectId`	`string` Required. Project that will be used for query execution and billing.
`query`	`string` Required. The query to execute in the form of a GoogleSQL query.
`dryRun`	`boolean` Optional. If set to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false.

projectId

string

Required. Project that will be used for query execution and billing.

query

string

Required. The query to execute in the form of a GoogleSQL query.

dryRun

boolean

Optional. If set to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false.

Output Schema

Response for a BigQuery SQL query.

JSON representation
{ "schema": { object (`TableSchema`) }, "rows": [ { object } ], "jobComplete": boolean, "errors": [ { object (`ErrorProto`) } ] }

Fields
`schema`	`object (TableSchema)` The schema of the results. Present only when the query completes successfully.
`rows[]`	`object (Struct format)` An object with as many results as can be contained within the maximum permitted reply size. To get any additional rows, you can call GetQueryResults and specify the jobReference returned above.
`jobComplete`	`boolean` Whether the query has completed or not. If rows or totalRows are present, this will always be true. If this is false, totalRows will not be available.
`errors[]`	`object (ErrorProto)` Output only. The first errors or warnings encountered during the running of the job. The final message includes the number of errors that caused the process to stop. Errors here do not necessarily mean that the job has completed or was unsuccessful. For more information about error messages, see Error messages.

JSON representation
{ "fields": [ { object (`TableFieldSchema`) } ], "foreignTypeInfo": { object (`ForeignTypeInfo`) } }

Fields

Fields
`fields[]`	`object (TableFieldSchema)` Describes the fields in a table.
`foreignTypeInfo`	`object (ForeignTypeInfo)` Optional. Specifies metadata of the foreign data type definition in field schema (`TableFieldSchema.foreign_type_definition`).

fields[]

object (TableFieldSchema)

Describes the fields in a table.

foreignTypeInfo

object (ForeignTypeInfo)

Optional. Specifies metadata of the foreign data type definition in field schema (TableFieldSchema.foreign_type_definition).

JSON representation

JSON representation
{ "name": string, "type": string, "mode": string, "fields": [ { object (`TableFieldSchema`) } ], "description": string, "policyTags": { object (`PolicyTagList`) }, "dataPolicies": [ { object (`DataPolicyOption`) } ], "nameAlternative": [ string ], "maxLength": string, "precision": string, "scale": string, "timestampPrecision": string, "roundingMode": enum (`RoundingMode`), "collation": string, "defaultValueExpression": string, "rangeElementType": { object (`FieldElementType`) }, "foreignTypeDefinition": string }

{
  "name": string,
  "type": string,
  "mode": string,
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "description": string,
  "policyTags": {
    object (PolicyTagList)
  },
  "dataPolicies": [
    {
      object (DataPolicyOption)
    }
  ],
  "nameAlternative": [
    string
  ],
  "maxLength": string,
  "precision": string,
  "scale": string,
  "timestampPrecision": string,
  "roundingMode": enum (RoundingMode),
  "collation": string,
  "defaultValueExpression": string,
  "rangeElementType": {
    object (FieldElementType)
  },
  "foreignTypeDefinition": string
}

Fields
`name`	`string` Required. The field name. The name must contain only letters (a-z, A-Z), numbers (0-9), or underscores (_), and must start with a letter or underscore. The maximum length is 300 characters.
`type`	`string` Required. The field data type. Possible values include: STRING BYTES INTEGER (or INT64) FLOAT (or FLOAT64) BOOLEAN (or BOOL) TIMESTAMP DATE TIME DATETIME GEOGRAPHY NUMERIC BIGNUMERIC JSON RECORD (or STRUCT) RANGE Use of RECORD/STRUCT indicates that the field contains a nested schema.
`mode`	`string` Optional. The field mode. Possible values include NULLABLE, REQUIRED and REPEATED. The default value is NULLABLE.
`fields[]`	`object (TableFieldSchema)` Optional. Describes the nested schema fields if the type property is set to RECORD.
`description`	`string` Optional. The field description. The maximum length is 1,024 characters.
`policyTags`	`object (PolicyTagList)` Optional. The policy tags attached to this field, used for field-level access control. If not set, defaults to empty policy_tags.
`dataPolicies[]`	`object (DataPolicyOption)` Optional. Data policies attached to this field, used for field-level access control.
`nameAlternative[]`	`string` This field should not be used.
`maxLength`	`string (int64 format)` Optional. Maximum length of values of this field for STRINGS or BYTES. If max_length is not specified, no maximum length constraint is imposed on this field. If type = "STRING", then max_length represents the maximum UTF-8 length of strings in this field. If type = "BYTES", then max_length represents the maximum number of bytes in this field. It is invalid to set this field if type ≠ "STRING" and ≠ "BYTES".
`precision`	`string (int64 format)` Optional. Precision (maximum number of total digits in base 10) and scale (maximum number of digits in the fractional part in base 10) constraints for values of this field for NUMERIC or BIGNUMERIC. It is invalid to set precision or scale if type ≠ "NUMERIC" and ≠ "BIGNUMERIC". If precision and scale are not specified, no value range constraint is imposed on this field insofar as values are permitted by the type. Values of this NUMERIC or BIGNUMERIC field must be in this range when: Precision (`P`) and scale (`S`) are specified: [-10^P-S + 10^-S, 10^P-S - 10^-S] Precision (`P`) is specified but not scale (and thus scale is interpreted to be equal to zero): [-10^P + 1, 10^P - 1]. Acceptable values for precision and scale if both are specified: If type = "NUMERIC": 1 ≤ precision - scale ≤ 29 and 0 ≤ scale ≤ 9. If type = "BIGNUMERIC": 1 ≤ precision - scale ≤ 38 and 0 ≤ scale ≤ 38. Acceptable values for precision if only precision is specified but not scale (and thus scale is interpreted to be equal to zero): If type = "NUMERIC": 1 ≤ precision ≤ 29. If type = "BIGNUMERIC": 1 ≤ precision ≤ 38. If scale is specified but not precision, then it is invalid.
`scale`	`string (int64 format)` Optional. See documentation for precision.
`timestampPrecision`	`string (Int64Value format)` Optional. Precision (maximum number of total digits in base 10) for seconds of TIMESTAMP type. Possible values include: * 6 (Default, for TIMESTAMP type with microsecond precision) * 12 (For TIMESTAMP type with picosecond precision)
`roundingMode`	`enum (RoundingMode)` Optional. Specifies the rounding mode to be used when storing values of NUMERIC and BIGNUMERIC type.
`collation`	`string` Optional. Field collation can be set only when the type of field is STRING. The following values are supported: 'und:ci': undetermined locale, case insensitive. '': empty string. Default to case-sensitive behavior.
`defaultValueExpression`	`string` Optional. A SQL expression to specify the default value for this field.
`rangeElementType`	`object (FieldElementType)` Optional. The subtype of the RANGE, if the type of this field is RANGE. If the type is RANGE, this field is required. Values for the field element type can be the following: DATE DATETIME TIMESTAMP
`foreignTypeDefinition`	`string` Optional. Definition of the foreign data type. Only valid for top-level schema fields (not nested fields). If the type is FOREIGN, this field is required.

JSON representation
{ "value": string }

Fields

Fields
`value`	`string` The string value.

value

string

The string value.

JSON representation
{ "names": [ string ] }

Fields

Fields
`names[]`	`string` A list of policy tag resource names. For example, "projects/1/locations/eu/taxonomies/2/policyTags/3". At most 1 policy tag is currently allowed.

names[]

string

A list of policy tag resource names. For example, "projects/1/locations/eu/taxonomies/2/policyTags/3". At most 1 policy tag is currently allowed.

JSON representation
{ // Union field `_name` can be only one of the following: "name": string // End of list of possible types for union field `_name`. }

Fields

Fields
Union field `_name`. `_name` can be only one of the following:
`name`	`string` Data policy resource name in the form of projects/project_id/locations/location_id/dataPolicies/data_policy_id.

Union field _name.

_name can be only one of the following:

name

string

Data policy resource name in the form of projects/project_id/locations/location_id/dataPolicies/data_policy_id.

JSON representation
{ "value": string }

Fields

Fields
`value`	`string (int64 format)` The int64 value.

value

string (int64 format)

The int64 value.

JSON representation
{ "type": string }

Fields

Fields
`type`	`string` Required. The type of a field element. For more information, see `TableFieldSchema.type`.

type

string

Required. The type of a field element. For more information, see TableFieldSchema.type.

JSON representation
{ "typeSystem": enum (`TypeSystem`) }

Fields

Fields
`typeSystem`	`enum (TypeSystem)` Required. Specifies the system which defines the foreign data type.

typeSystem

enum (TypeSystem)

Required. Specifies the system which defines the foreign data type.

JSON representation
{ "fields": { string: value, ... } }

Fields

Fields
`fields`	`map (key: string, value: value (Value format))` Unordered map of dynamically typed values. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`.

fields

map (key: string, value: value (Value format))

Unordered map of dynamically typed values.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

JSON representation
{ "key": string, "value": value }

Fields
`key`	`string`
`value`	`value (Value format)`

JSON representation

JSON representation
{ // Union field `kind` can be only one of the following: "nullValue": null, "numberValue": number, "stringValue": string, "boolValue": boolean, "structValue": { object }, "listValue": array // End of list of possible types for union field `kind`. }

{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}

Fields
Union field `kind`. The kind of value. `kind` can be only one of the following:
`nullValue`	`null` Represents a null value.
`numberValue`	`number` Represents a double value.
`stringValue`	`string` Represents a string value.
`boolValue`	`boolean` Represents a boolean value.
`structValue`	`object (Struct format)` Represents a structured value.
`listValue`	`array (ListValue format)` Represents a repeated `Value`.

JSON representation
{ "values": [ value ] }

Fields

Fields
`values[]`	`value (Value format)` Repeated field of dynamically typed values.

values[]

value (Value format)

Repeated field of dynamically typed values.

JSON representation
{ "value": boolean }

Fields

Fields
`value`	`boolean` The bool value.

value

boolean

The bool value.

JSON representation
{ "reason": string, "location": string, "debugInfo": string, "message": string }

Fields
`reason`	`string` A short error code that summarizes the error.
`location`	`string` Specifies where the error occurred, if present.
`debugInfo`	`string` Debugging information. This property is internal to Google and should not be used.
`message`	`string` A human-readable description of the error.

Tool Annotations

Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅

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

Tool: execute_sql

Input Schema

Output Schema

Tool Annotations

MCP Tools Reference: bigquery.googleapis.com

Tool: `execute_sql`