diff --git a/DEVELOPER.md b/DEVELOPER.md index d7d0eb437d..62a90132a4 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -132,7 +132,7 @@ ## Developing Documentation -1. [Install Hugo](https://gohugo.io/installation/macos/) +1. [Install Hugo](https://gohugo.io/installation/macos/) version 0.145.0. This version is currently required due to breaking changes. 1. Move into the `.hugo` directory ```bash diff --git a/docs/en/how-to/connect-ide/alloydb_pg_mcp.md b/docs/en/how-to/connect-ide/alloydb_pg_mcp.md index 753f2a85ad..d13bc6a83c 100644 --- a/docs/en/how-to/connect-ide/alloydb_pg_mcp.md +++ b/docs/en/how-to/connect-ide/alloydb_pg_mcp.md @@ -45,24 +45,24 @@ description: > ## Install MCP Toolbox -1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.5.0+: +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: {{< tabpane persist=header >}} {{< tab header="linux/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/linux/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox {{< /tab >}} {{< tab header="darwin/arm64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/arm64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox {{< /tab >}} {{< tab header="darwin/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox {{< /tab >}} {{< tab header="windows/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox {{< /tab >}} {{< /tabpane >}} @@ -80,255 +80,147 @@ curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbo ./toolbox --version ``` -## Configure and run Toolbox - -This section will create a `tools.yaml` file, which will define which tools your AI Agent will have access to. You can add, remove, or edit tools as needed to make sure you have the best tools for your workflows. - -This will configure the following tools: - -1. **list_tables**: lists tables and descriptions -3. **execute_sql**: execute any SQL statement - -To configure Toolbox, run the following steps: - -1. Set the following environment variables: - - ```bash - # The ID of your Google Cloud Project where the AlloyDB cluster/instance is located. - export ALLOYDB_PROJECT="your-gcp-project-id" - - # The region where your AlloyDB cluster is located (e.g., us-central1). - export ALLOYDB_REGION="your-cluster-region" - - # The name of your AlloyDB cluster. - export ALLOYDB_CLUSTER="your-cluster-name" - - # The name of your AlloyDB instance. - export ALLOYDB_INSTANCE="your-instance-name" - - # The name of the database you want to connect to within the instance. - export ALLOYDB_DB="your-database-name" - - # The username for connecting to the database. - export ALLOYDB_USER="your-database-user" - - # The password for the specified database user. - export ALLOYDB_PASS="your-database-password" - ``` - -2. Create a `tools.yaml` file. - -3. Copy and paste the following contents into the `tools.yaml`: - - ```yaml - sources: - alloydb-pg-source: - kind: alloydb-postgres - project: ${ALLOYDB_PROJECT} - region: ${ALLOYDB_REGION} - cluster: ${ALLOYDB_CLUSTER} - instance: ${ALLOYDB_INSTANCE} - database: ${ALLOYDB_DB} - user: ${ALLOYDB_USER} - password: ${ALLOYDB_PASS} - - tools: - execute_sql: - kind: postgres-execute-sql - source: alloydb-pg-source - description: Use this tool to execute sql. - - list_tables: - kind: postgres-sql - source: alloydb-pg-source - description: "Lists detailed schema information (object type, columns, constraints, indexes, triggers, owner, comment) as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. If names are omitted, lists all tables in user schemas." - statement: | - WITH desired_relkinds AS ( - SELECT ARRAY['r', 'p']::char[] AS kinds -- Always consider both 'TABLE' and 'PARTITIONED TABLE' - ), - table_info AS ( - SELECT - t.oid AS table_oid, - ns.nspname AS schema_name, - t.relname AS table_name, - pg_get_userbyid(t.relowner) AS table_owner, - obj_description(t.oid, 'pg_class') AS table_comment, - t.relkind AS object_kind - FROM - pg_class t - JOIN - pg_namespace ns ON ns.oid = t.relnamespace - CROSS JOIN desired_relkinds dk - WHERE - t.relkind = ANY(dk.kinds) -- Filter by selected table relkinds ('r', 'p') - AND (NULLIF(TRIM($1), '') IS NULL OR t.relname = ANY(string_to_array($1,','))) -- $1 is object_names - AND ns.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast') - AND ns.nspname NOT LIKE 'pg_temp_%' AND ns.nspname NOT LIKE 'pg_toast_temp_%' - ), - columns_info AS ( - SELECT - att.attrelid AS table_oid, att.attname AS column_name, format_type(att.atttypid, att.atttypmod) AS data_type, - att.attnum AS column_ordinal_position, att.attnotnull AS is_not_nullable, - pg_get_expr(ad.adbin, ad.adrelid) AS column_default, col_description(att.attrelid, att.attnum) AS column_comment - FROM pg_attribute att LEFT JOIN pg_attrdef ad ON att.attrelid = ad.adrelid AND att.attnum = ad.adnum - JOIN table_info ti ON att.attrelid = ti.table_oid WHERE att.attnum > 0 AND NOT att.attisdropped - ), - constraints_info AS ( - SELECT - con.conrelid AS table_oid, con.conname AS constraint_name, pg_get_constraintdef(con.oid) AS constraint_definition, - CASE con.contype WHEN 'p' THEN 'PRIMARY KEY' WHEN 'f' THEN 'FOREIGN KEY' WHEN 'u' THEN 'UNIQUE' WHEN 'c' THEN 'CHECK' ELSE con.contype::text END AS constraint_type, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = u.attnum) AS constraint_columns, - NULLIF(con.confrelid, 0)::regclass AS foreign_key_referenced_table, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.confkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.confrelid AND att.attnum = u.attnum WHERE con.contype = 'f') AS foreign_key_referenced_columns - FROM pg_constraint con JOIN table_info ti ON con.conrelid = ti.table_oid - ), - indexes_info AS ( - SELECT - idx.indrelid AS table_oid, ic.relname AS index_name, pg_get_indexdef(idx.indexrelid) AS index_definition, - idx.indisunique AS is_unique, idx.indisprimary AS is_primary, am.amname AS index_method, - (SELECT array_agg(att.attname ORDER BY u.ord) FROM unnest(idx.indkey::int[]) WITH ORDINALITY AS u(colidx, ord) LEFT JOIN pg_attribute att ON att.attrelid = idx.indrelid AND att.attnum = u.colidx WHERE u.colidx <> 0) AS index_columns - FROM pg_index idx JOIN pg_class ic ON ic.oid = idx.indexrelid JOIN pg_am am ON am.oid = ic.relam JOIN table_info ti ON idx.indrelid = ti.table_oid - ), - triggers_info AS ( - SELECT tg.tgrelid AS table_oid, tg.tgname AS trigger_name, pg_get_triggerdef(tg.oid) AS trigger_definition, tg.tgenabled AS trigger_enabled_state - FROM pg_trigger tg JOIN table_info ti ON tg.tgrelid = ti.table_oid WHERE NOT tg.tgisinternal - ) - SELECT - ti.schema_name, - ti.table_name AS object_name, - json_build_object( - 'schema_name', ti.schema_name, - 'object_name', ti.table_name, - 'object_type', CASE ti.object_kind - WHEN 'r' THEN 'TABLE' - WHEN 'p' THEN 'PARTITIONED TABLE' - ELSE ti.object_kind::text -- Should not happen due to WHERE clause - END, - 'owner', ti.table_owner, - 'comment', ti.table_comment, - 'columns', COALESCE((SELECT json_agg(json_build_object('column_name',ci.column_name,'data_type',ci.data_type,'ordinal_position',ci.column_ordinal_position,'is_not_nullable',ci.is_not_nullable,'column_default',ci.column_default,'column_comment',ci.column_comment) ORDER BY ci.column_ordinal_position) FROM columns_info ci WHERE ci.table_oid = ti.table_oid), '[]'::json), - 'constraints', COALESCE((SELECT json_agg(json_build_object('constraint_name',cons.constraint_name,'constraint_type',cons.constraint_type,'constraint_definition',cons.constraint_definition,'constraint_columns',cons.constraint_columns,'foreign_key_referenced_table',cons.foreign_key_referenced_table,'foreign_key_referenced_columns',cons.foreign_key_referenced_columns)) FROM constraints_info cons WHERE cons.table_oid = ti.table_oid), '[]'::json), - 'indexes', COALESCE((SELECT json_agg(json_build_object('index_name',ii.index_name,'index_definition',ii.index_definition,'is_unique',ii.is_unique,'is_primary',ii.is_primary,'index_method',ii.index_method,'index_columns',ii.index_columns)) FROM indexes_info ii WHERE ii.table_oid = ti.table_oid), '[]'::json), - 'triggers', COALESCE((SELECT json_agg(json_build_object('trigger_name',tri.trigger_name,'trigger_definition',tri.trigger_definition,'trigger_enabled_state',tri.trigger_enabled_state)) FROM triggers_info tri WHERE tri.table_oid = ti.table_oid), '[]'::json) - ) AS object_details - FROM table_info ti ORDER BY ti.schema_name, ti.table_name; - parameters: - - name: table_names - type: string - description: "Optional: A comma-separated list of table names. If empty, details for all tables in user-accessible schemas will be listed." - ``` - -4. Start Toolbox to listen on `127.0.0.1:5000`: - - ```bash - ./toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 - ``` - -{{< notice tip >}} -To stop the Toolbox server when you're finished, press `ctrl+c` to send the terminate signal. -{{< /notice >}} - ## Configure your MCP Client {{< tabpane text=true >}} {{% tab header="Claude code" lang="en" %}} 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). -2. Create a `.mcp.json` file in your project root if it doesn't exist. -3. Add the following configuration and save: +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } ``` -4. Restart Claude code to apply the new configuration. +1. Restart Claude code to apply the new configuration. {{% /tab %}} {{% tab header="Claude desktop" lang="en" %}} -1. Install [`npx`](https://docs.npmjs.com/cli/v8/commands/npx). -2. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. -3. Under the Developer tab, tap Edit Config to open the configuration file. -4. Add the following configuration and save: +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "http://127.0.0.1:5000/mcp/sse" - ] + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } ``` -5. Restart Claude desktop. -6. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. {{% /tab %}} {{% tab header="Cline" lang="en" %}} 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. -2. Tap Configure MCP Servers to open the configuration file. -3. Add the following configuration and save: +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } ``` -4. You should see a green active status after the server is successfully connected. +1. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Cursor" lang="en" %}} 1. Create a `.cursor` directory in your project root if it doesn't exist. -2. Create a `.cursor/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } ``` -4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Visual Studio Code (Copilot)" lang="en" %}} 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. -2. Create a `.vscode/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } @@ -338,14 +230,24 @@ To stop the Toolbox server when you're finished, press `ctrl+c` to send the term {{% tab header="Windsurf" lang="en" %}} 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. -2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. -3. Add the following configuration: +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "alloydb": { - "serverUrl": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","alloydb-postgres","--stdio"], + "env": { + "ALLOYDB_POSTGRES_PROJECT": "your-gcp-project-id", + "ALLOYDB_POSTGRES_REGION": "your-cluster-region", + "ALLOYDB_POSTGRES_CLUSTER": "your-cluster-name", + "ALLOYDB_POSTGRES_INSTANCE": "your-instance-name", + "ALLOYDB_POSTGRES_DATABASE": "your-database-name", + "ALLOYDB_POSTGRES_USER": "your-database-user", + "ALLOYDB_POSTGRES_PASSWORD": "your-database-password" + } } } } diff --git a/docs/en/how-to/connect-ide/bigquery_mcp.md b/docs/en/how-to/connect-ide/bigquery_mcp.md new file mode 100644 index 0000000000..9cb4049ae2 --- /dev/null +++ b/docs/en/how-to/connect-ide/bigquery_mcp.md @@ -0,0 +1,223 @@ +--- +title: "BigQuery using MCP" +type: docs +weight: 2 +description: > + Connect your IDE to BigQuery using Toolbox. +--- + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like BigQuery. This guide covers how to use [MCP Toolbox for Databases][toolbox] to expose your developer assistant tools to a BigQuery instance: + +* [Cursor][cursor] +* [Windsurf][windsurf] (Codium) +* [Visual Studio Code ][vscode] (Copilot) +* [Cline][cline] (VS Code extension) +* [Claude desktop][claudedesktop] +* [Claude code][claudecode] + +[toolbox]: https://github.com/googleapis/genai-toolbox +[cursor]: #configure-your-mcp-client +[windsurf]: #configure-your-mcp-client +[vscode]: #configure-your-mcp-client +[cline]: #configure-your-mcp-client +[claudedesktop]: #configure-your-mcp-client +[claudecode]: #configure-your-mcp-client + +## Before you begin + +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. + +1. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project). + + +## Set up the database + +1. [Enable the BigQuery API in the Google Cloud project](https://console.cloud.google.com/flows/enableapi?apiid=bigquery.googleapis.com&redirect=https://console.cloud.google.com). + +1. Configure the required roles and permissions to complete this task. You will need [BigQuery User](https://cloud.google.com/bigquery/docs/access-control) role (`roles/bigquery.user`), BigQuery Data Viewer role(`roles/bigquery.dataViewer`), or equivalent IAM permissions to connect to the instance. + +1. Configured [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for your environment. + +## Install MCP Toolbox + +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: + + + {{< tabpane persist=header >}} +{{< tab header="linux/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox +{{< /tab >}} + +{{< tab header="darwin/arm64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox +{{< /tab >}} + +{{< tab header="darwin/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox +{{< /tab >}} + +{{< tab header="windows/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox +{{< /tab >}} +{{< /tabpane >}} + + + +1. Make the binary executable: + + ```bash + chmod +x toolbox + ``` + +1. Verify the installation: + + ```bash + ./toolbox --version + ``` + +## Configure your MCP Client + +{{< tabpane text=true >}} +{{% tab header="Claude code" lang="en" %}} + +1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +1. Restart Claude code to apply the new configuration. +{{% /tab %}} + +{{% tab header="Claude desktop" lang="en" %}} + +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +{{% /tab %}} + +{{% tab header="Cline" lang="en" %}} + +1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +1. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Cursor" lang="en" %}} + +1. Create a `.cursor` directory in your project root if it doesn't exist. +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Visual Studio Code (Copilot)" lang="en" %}} + +1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +{{% /tab %}} + +{{% tab header="Windsurf" lang="en" %}} + +1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "bigquery": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","bigquery","--stdio"], + "env": { + "BIGQUERY_PROJECT": "" + } + } + } + } + ``` + + +{{% /tab %}} +{{< /tabpane >}} diff --git a/docs/en/how-to/connect-ide/cloud_sql_mssql_mcp.md b/docs/en/how-to/connect-ide/cloud_sql_mssql_mcp.md new file mode 100644 index 0000000000..4a875cbbfa --- /dev/null +++ b/docs/en/how-to/connect-ide/cloud_sql_mssql_mcp.md @@ -0,0 +1,256 @@ +--- +title: "Cloud SQL for SQL Server using MCP" +type: docs +weight: 2 +description: > + Connect your IDE to Cloud SQl for SQL Server using Toolbox. +--- + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Cloud SQL. This guide covers how to use [MCP Toolbox for Databases][toolbox] to expose your developer assistant tools to a Cloud SQL for SQL Server instance: + +* [Cursor][cursor] +* [Windsurf][windsurf] (Codium) +* [Visual Studio Code ][vscode] (Copilot) +* [Cline][cline] (VS Code extension) +* [Claude desktop][claudedesktop] +* [Claude code][claudecode] + +[toolbox]: https://github.com/googleapis/genai-toolbox +[cursor]: #configure-your-mcp-client +[windsurf]: #configure-your-mcp-client +[vscode]: #configure-your-mcp-client +[cline]: #configure-your-mcp-client +[claudedesktop]: #configure-your-mcp-client +[claudecode]: #configure-your-mcp-client + +## Before you begin + +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. + +1. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project). + + +## Set up the database + +1. [Enable the Cloud SQL Admin API in the Google Cloud project](https://console.cloud.google.com/flows/enableapi?apiid=sqladmin&redirect=https://console.cloud.google.com). + +1. [Create or select a Cloud SQL for SQL Server instance](https://cloud.google.com/sql/docs/sqlserver/create-instance). These instructions assume that your Cloud SQL instance has a [public IP address](https://cloud.google.com/sql/docs/sqlserver/configure-ip). By default, Cloud SQL assigns a public IP address to a new instance. Toolbox will connect securely using the [Cloud SQL connectors](https://cloud.google.com/sql/docs/sqlserver/language-connectors). + +1. Configure the required roles and permissions to complete this task. You will need [Cloud SQL > Client](https://cloud.google.com/sql/docs/sqlserver/roles-and-permissions#proxy-roles-permissions) role (`roles/cloudsql.client`) or equivalent IAM permissions to connect to the instance. + +1. Configured [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for your environment. + +1. Create or reuse [a database user](https://cloud.google.com/sql/docs/sqlserver/create-manage-users) and have the username and password ready. + + +## Install MCP Toolbox + +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: + + + {{< tabpane persist=header >}} +{{< tab header="linux/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox +{{< /tab >}} + +{{< tab header="darwin/arm64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox +{{< /tab >}} + +{{< tab header="darwin/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox +{{< /tab >}} + +{{< tab header="windows/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox +{{< /tab >}} +{{< /tabpane >}} + + + +1. Make the binary executable: + + ```bash + chmod +x toolbox + ``` + +1. Verify the installation: + + ```bash + ./toolbox --version + ``` + +## Configure your MCP Client + +{{< tabpane text=true >}} +{{% tab header="Claude code" lang="en" %}} + +1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + ``` + +1. Restart Claude code to apply the new configuration. +{{% /tab %}} + +{{% tab header="Claude desktop" lang="en" %}} + +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + } + ``` + +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +{{% /tab %}} + +{{% tab header="Cline" lang="en" %}} + +1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + } + ``` + +1. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Cursor" lang="en" %}} + +1. Create a `.cursor` directory in your project root if it doesn't exist. +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + } + ``` + +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Visual Studio Code (Copilot)" lang="en" %}} + +1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + } + ``` +{{% /tab %}} + +{{% tab header="Windsurf" lang="en" %}} + +1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-sqlserver": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mssql","--stdio"], + "env": { + "CLOUD_SQL_MSSQL_PROJECT": "", + "CLOUD_SQL_MSSQL_REGION": "", + "CLOUD_SQL_MSSQL_INSTANCE": "", + "CLOUD_SQL_MSSQL_DATABASE": "", + "CLOUD_SQL_MSSQL_IP_ADDRESS": "", + "CLOUD_SQL_MSSQL_USER": "", + "CLOUD_SQL_MSSQL_PASSWORD": "" + } + } + } + } + + ``` +{{% /tab %}} +{{< /tabpane >}} diff --git a/docs/en/how-to/connect-ide/cloud_sql_mysql_mcp.md b/docs/en/how-to/connect-ide/cloud_sql_mysql_mcp.md new file mode 100644 index 0000000000..02a163ff24 --- /dev/null +++ b/docs/en/how-to/connect-ide/cloud_sql_mysql_mcp.md @@ -0,0 +1,250 @@ +--- +title: "Cloud SQL for MySQL using MCP" +type: docs +weight: 2 +description: > + Connect your IDE to Cloud SQl for MySQL using Toolbox. +--- + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Cloud SQL. This guide covers how to use [MCP Toolbox for Databases][toolbox] to expose your developer assistant tools to a Cloud SQL for MySQL instance: + +* [Cursor][cursor] +* [Windsurf][windsurf] (Codium) +* [Visual Studio Code ][vscode] (Copilot) +* [Cline][cline] (VS Code extension) +* [Claude desktop][claudedesktop] +* [Claude code][claudecode] + +[toolbox]: https://github.com/googleapis/genai-toolbox +[cursor]: #configure-your-mcp-client +[windsurf]: #configure-your-mcp-client +[vscode]: #configure-your-mcp-client +[cline]: #configure-your-mcp-client +[claudedesktop]: #configure-your-mcp-client +[claudecode]: #configure-your-mcp-client + +## Before you begin + +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. + +1. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project). + + +## Set up the database + +1. [Enable the Cloud SQL Admin API in the Google Cloud project](https://console.cloud.google.com/flows/enableapi?apiid=sqladmin&redirect=https://console.cloud.google.com). + +1. [Create a Cloud SQL for MySQL instance](https://cloud.google.com/sql/docs/mysql/create-instance). These instructions assume that your Cloud SQL instance has a [public IP address](https://cloud.google.com/sql/docs/mysql/configure-ip). By default, Cloud SQL assigns a public IP address to a new instance. Toolbox will connect securely using the [Cloud SQL connectors](https://cloud.google.com/sql/docs/mysql/language-connectors). + +1. Configure the required roles and permissions to complete this task. You will need [Cloud SQL > Client](https://cloud.google.com/sql/docs/mysql/roles-and-permissions#proxy-roles-permissions) role (`roles/cloudsql.client`) or equivalent IAM permissions to connect to the instance. + +1. Configured [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for your environment. + +1. Create or reuse [a database user](https://cloud.google.com/sql/docs/mysql/create-manage-users) and have the username and password ready. + + +## Install MCP Toolbox + +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: + + + {{< tabpane persist=header >}} +{{< tab header="linux/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox +{{< /tab >}} + +{{< tab header="darwin/arm64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox +{{< /tab >}} + +{{< tab header="darwin/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox +{{< /tab >}} + +{{< tab header="windows/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox +{{< /tab >}} +{{< /tabpane >}} + + + +1. Make the binary executable: + + ```bash + chmod +x toolbox + ``` + +1. Verify the installation: + + ```bash + ./toolbox --version + ``` + +## Configure your MCP Client + +{{< tabpane text=true >}} +{{% tab header="Claude code" lang="en" %}} + +1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + } + ``` + +1. Restart Claude code to apply the new configuration. +{{% /tab %}} + +{{% tab header="Claude desktop" lang="en" %}} + +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + } + ``` + +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +{{% /tab %}} + +{{% tab header="Cline" lang="en" %}} + +1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + } + ``` + +1. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Cursor" lang="en" %}} + +1. Create a `.cursor` directory in your project root if it doesn't exist. +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + ``` + +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Visual Studio Code (Copilot)" lang="en" %}} + +1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + } + ``` +{{% /tab %}} + +{{% tab header="Windsurf" lang="en" %}} + +1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + ```json + { + "mcpServers": { + "cloud-sql-mysql": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-mysql","--stdio"], + "env": { + "CLOUD_SQL_MYSQL_PROJECT": "", + "CLOUD_SQL_MYSQL_REGION": "", + "CLOUD_SQL_MYSQL_INSTANCE": "", + "CLOUD_SQL_MYSQL_DATABASE": "", + "CLOUD_SQL_MYSQL_USER": "", + "CLOUD_SQL_MYSQL_PASSWORD": "" + } + } + } + } + + ``` +{{% /tab %}} +{{< /tabpane >}} diff --git a/docs/en/how-to/connect-ide/cloud_sql_pg_mcp.md b/docs/en/how-to/connect-ide/cloud_sql_pg_mcp.md index 90aad84b95..3ce394e5c6 100644 --- a/docs/en/how-to/connect-ide/cloud_sql_pg_mcp.md +++ b/docs/en/how-to/connect-ide/cloud_sql_pg_mcp.md @@ -1,5 +1,5 @@ --- -title: "Cloud SQL using MCP" +title: "Cloud SQL for Postgres using MCP" type: docs weight: 2 description: > @@ -34,7 +34,7 @@ description: > 1. [Enable the Cloud SQL Admin API in the Google Cloud project](https://console.cloud.google.com/flows/enableapi?apiid=sqladmin&redirect=https://console.cloud.google.com). -1. [Create a Cloud SQL for PostgreSQL instance](https://cloud.google.com/sql/docs/postgres/create-instance). These instructions assume that your Cloud SQL instance has a [public IP address](https://cloud.google.com/sql/docs/postgres/configure-ip). By default, Cloud SQL assigns a public IP address to a new instance. Toolbox will connect securely using the [Cloud SQL connectors](https://cloud.google.com/sql/docs/postgres/language-connectors). +1. [Create or select a Cloud SQL for PostgreSQL instance](https://cloud.google.com/sql/docs/postgres/create-instance). These instructions assume that your Cloud SQL instance has a [public IP address](https://cloud.google.com/sql/docs/postgres/configure-ip). By default, Cloud SQL assigns a public IP address to a new instance. Toolbox will connect securely using the [Cloud SQL connectors](https://cloud.google.com/sql/docs/postgres/language-connectors). 1. Configure the required roles and permissions to complete this task. You will need [Cloud SQL > Client](https://cloud.google.com/sql/docs/postgres/roles-and-permissions#proxy-roles-permissions) role (`roles/cloudsql.client`) or equivalent IAM permissions to connect to the instance. @@ -45,24 +45,24 @@ description: > ## Install MCP Toolbox -1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.5.0+: +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: {{< tabpane persist=header >}} {{< tab header="linux/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/linux/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox {{< /tab >}} {{< tab header="darwin/arm64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/arm64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox {{< /tab >}} {{< tab header="darwin/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox {{< /tab >}} {{< tab header="windows/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox {{< /tab >}} {{< /tabpane >}} @@ -80,253 +80,142 @@ curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbo ./toolbox --version ``` -## Configure and run Toolbox - -This section will create a `tools.yaml` file, which will define which tools your AI Agent will have access to. You can add, remove, or edit tools as needed to make sure you have the best tools for your workflows. - -This will configure the following tools: - -1. **list_tables**: lists tables and descriptions -3. **execute_sql**: execute any SQL statement - -To configure Toolbox, run the following steps: - -1. Set the following environment variables: - - ```bash - # The ID of your Google Cloud Project where the Cloud SQL instance is located. - export CLOUD_SQL_PROJECT="your-gcp-project-id" - - # The region where your Cloud SQL instance is located (e.g., us-central1). - export CLOUD_SQL_REGION="your-instance-region" - - # The name of your Cloud SQL instance. - export CLOUD_SQL_INSTANCE="your-instance-name" - - # The name of the database you want to connect to within the instance. - export CLOUD_SQL_DB="your-database-name" - - # The username for connecting to the database. - export CLOUD_SQL_USER="your-database-user" - - # The password for the specified database user. - export CLOUD_SQL_PASS="your-database-password" - ``` - -2. Create a `tools.yaml` file. - -3. Copy and paste the following contents into the `tools.yaml`: - - ```yaml - sources: - cloudsql-pg-source: - kind: cloud-sql-postgres - project: ${CLOUD_SQL_PROJECT} - region: ${CLOUD_SQL_REGION} - instance: ${CLOUD_SQL_INSTANCE} - database: ${CLOUD_SQL_DB} - user: ${CLOUD_SQL_USER} - password: ${CLOUD_SQL_PASS} - tools: - execute_sql: - kind: postgres-execute-sql - source: cloudsql-pg-source - description: Use this tool to execute SQL - - list_tables: - kind: postgres-sql - source: cloudsql-pg-source - description: > - Lists detailed table information (object type, columns, constraints, indexes, triggers, owner, comment) - as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. - If names are omitted, lists all tables in user schemas - statement: | - WITH desired_relkinds AS ( - SELECT ARRAY['r', 'p']::char[] AS kinds -- Always consider both 'TABLE' and 'PARTITIONED TABLE' - ), - table_info AS ( - SELECT - t.oid AS table_oid, - ns.nspname AS schema_name, - t.relname AS table_name, - pg_get_userbyid(t.relowner) AS table_owner, - obj_description(t.oid, 'pg_class') AS table_comment, - t.relkind AS object_kind - FROM - pg_class t - JOIN - pg_namespace ns ON ns.oid = t.relnamespace - CROSS JOIN desired_relkinds dk - WHERE - t.relkind = ANY(dk.kinds) -- Filter by selected table relkinds ('r', 'p') - AND (NULLIF(TRIM($1), '') IS NULL OR t.relname = ANY(string_to_array($1,','))) -- $1 is object_names - AND ns.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast') - AND ns.nspname NOT LIKE 'pg_temp_%' AND ns.nspname NOT LIKE 'pg_toast_temp_%' - ), - columns_info AS ( - SELECT - att.attrelid AS table_oid, att.attname AS column_name, format_type(att.atttypid, att.atttypmod) AS data_type, - att.attnum AS column_ordinal_position, att.attnotnull AS is_not_nullable, - pg_get_expr(ad.adbin, ad.adrelid) AS column_default, col_description(att.attrelid, att.attnum) AS column_comment - FROM pg_attribute att LEFT JOIN pg_attrdef ad ON att.attrelid = ad.adrelid AND att.attnum = ad.adnum - JOIN table_info ti ON att.attrelid = ti.table_oid WHERE att.attnum > 0 AND NOT att.attisdropped - ), - constraints_info AS ( - SELECT - con.conrelid AS table_oid, con.conname AS constraint_name, pg_get_constraintdef(con.oid) AS constraint_definition, - CASE con.contype WHEN 'p' THEN 'PRIMARY KEY' WHEN 'f' THEN 'FOREIGN KEY' WHEN 'u' THEN 'UNIQUE' WHEN 'c' THEN 'CHECK' ELSE con.contype::text END AS constraint_type, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = u.attnum) AS constraint_columns, - NULLIF(con.confrelid, 0)::regclass AS foreign_key_referenced_table, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.confkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.confrelid AND att.attnum = u.attnum WHERE con.contype = 'f') AS foreign_key_referenced_columns - FROM pg_constraint con JOIN table_info ti ON con.conrelid = ti.table_oid - ), - indexes_info AS ( - SELECT - idx.indrelid AS table_oid, ic.relname AS index_name, pg_get_indexdef(idx.indexrelid) AS index_definition, - idx.indisunique AS is_unique, idx.indisprimary AS is_primary, am.amname AS index_method, - (SELECT array_agg(att.attname ORDER BY u.ord) FROM unnest(idx.indkey::int[]) WITH ORDINALITY AS u(colidx, ord) LEFT JOIN pg_attribute att ON att.attrelid = idx.indrelid AND att.attnum = u.colidx WHERE u.colidx <> 0) AS index_columns - FROM pg_index idx JOIN pg_class ic ON ic.oid = idx.indexrelid JOIN pg_am am ON am.oid = ic.relam JOIN table_info ti ON idx.indrelid = ti.table_oid - ), - triggers_info AS ( - SELECT tg.tgrelid AS table_oid, tg.tgname AS trigger_name, pg_get_triggerdef(tg.oid) AS trigger_definition, tg.tgenabled AS trigger_enabled_state - FROM pg_trigger tg JOIN table_info ti ON tg.tgrelid = ti.table_oid WHERE NOT tg.tgisinternal - ) - SELECT - ti.schema_name, - ti.table_name AS object_name, - json_build_object( - 'schema_name', ti.schema_name, - 'object_name', ti.table_name, - 'object_type', CASE ti.object_kind - WHEN 'r' THEN 'TABLE' - WHEN 'p' THEN 'PARTITIONED TABLE' - ELSE ti.object_kind::text -- Should not happen due to WHERE clause - END, - 'owner', ti.table_owner, - 'comment', ti.table_comment, - 'columns', COALESCE((SELECT json_agg(json_build_object('column_name',ci.column_name,'data_type',ci.data_type,'ordinal_position',ci.column_ordinal_position,'is_not_nullable',ci.is_not_nullable,'column_default',ci.column_default,'column_comment',ci.column_comment) ORDER BY ci.column_ordinal_position) FROM columns_info ci WHERE ci.table_oid = ti.table_oid), '[]'::json), - 'constraints', COALESCE((SELECT json_agg(json_build_object('constraint_name',cons.constraint_name,'constraint_type',cons.constraint_type,'constraint_definition',cons.constraint_definition,'constraint_columns',cons.constraint_columns,'foreign_key_referenced_table',cons.foreign_key_referenced_table,'foreign_key_referenced_columns',cons.foreign_key_referenced_columns)) FROM constraints_info cons WHERE cons.table_oid = ti.table_oid), '[]'::json), - 'indexes', COALESCE((SELECT json_agg(json_build_object('index_name',ii.index_name,'index_definition',ii.index_definition,'is_unique',ii.is_unique,'is_primary',ii.is_primary,'index_method',ii.index_method,'index_columns',ii.index_columns)) FROM indexes_info ii WHERE ii.table_oid = ti.table_oid), '[]'::json), - 'triggers', COALESCE((SELECT json_agg(json_build_object('trigger_name',tri.trigger_name,'trigger_definition',tri.trigger_definition,'trigger_enabled_state',tri.trigger_enabled_state)) FROM triggers_info tri WHERE tri.table_oid = ti.table_oid), '[]'::json) - ) AS object_details - FROM table_info ti ORDER BY ti.schema_name, ti.table_name; - parameters: - - name: table_names - type: string - description: "Optional: A comma-separated list of table names. If empty, details for all tables in user-accessible schemas will be listed." - ``` - -4. Start Toolbox to listen on `127.0.0.1:5000`: - - ```bash - ./toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 - ``` - -{{< notice tip >}} -To stop the Toolbox server when you're finished, press `ctrl+c` to send the terminate signal. -{{< /notice >}} - ## Configure your MCP Client {{< tabpane text=true >}} {{% tab header="Claude code" lang="en" %}} 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). -2. Create a `.mcp.json` file in your project root if it doesn't exist. -3. Add the following configuration and save: +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } ``` -4. Restart Claude code to apply the new configuration. +1. Restart Claude code to apply the new configuration. {{% /tab %}} {{% tab header="Claude desktop" lang="en" %}} -1. Install [`npx`](https://docs.npmjs.com/cli/v8/commands/npx). -2. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. -3. Under the Developer tab, tap Edit Config to open the configuration file. -4. Add the following configuration and save: +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "http://127.0.0.1:5000/mcp/sse" - ] + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } ``` -5. Restart Claude desktop. -6. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. {{% /tab %}} {{% tab header="Cline" lang="en" %}} 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. -2. Tap Configure MCP Servers to open the configuration file. -3. Add the following configuration and save: +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } ``` -4. You should see a green active status after the server is successfully connected. +1. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Cursor" lang="en" %}} 1. Create a `.cursor` directory in your project root if it doesn't exist. -2. Create a `.cursor/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } ``` -4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Visual Studio Code (Copilot)" lang="en" %}} 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. -2. Create a `.vscode/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } @@ -336,14 +225,23 @@ To stop the Toolbox server when you're finished, press `ctrl+c` to send the term {{% tab header="Windsurf" lang="en" %}} 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. -2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. -3. Add the following configuration: +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "cloud-sql-postgres": { - "serverUrl": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","cloud-sql-postgres","--stdio"], + "env": { + "CLOUD_SQL_POSTGRES_PROJECT": "", + "CLOUD_SQL_POSTGRES_REGION": "", + "CLOUD_SQL_POSTGRES_INSTANCE": "", + "CLOUD_SQL_POSTGRES_DATABASE": "", + "CLOUD_SQL_POSTGRES_USER": "", + "CLOUD_SQL_POSTGRES_PASSWORD": "" + } } } } diff --git a/docs/en/how-to/connect-ide/postgres_mcp.md b/docs/en/how-to/connect-ide/postgres_mcp.md index 39001d4df3..2565677489 100644 --- a/docs/en/how-to/connect-ide/postgres_mcp.md +++ b/docs/en/how-to/connect-ide/postgres_mcp.md @@ -39,24 +39,24 @@ This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni ## Install MCP Toolbox -1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.5.0+: +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: {{< tabpane persist=header >}} {{< tab header="linux/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/linux/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox {{< /tab >}} {{< tab header="darwin/arm64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/arm64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox {{< /tab >}} {{< tab header="darwin/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/darwin/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox {{< /tab >}} {{< tab header="windows/amd64" lang="bash" >}} -curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbox +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox {{< /tab >}} {{< /tabpane >}} @@ -74,248 +74,137 @@ curl -O https://storage.googleapis.com/genai-toolbox/v0.5.0/windows/amd64/toolbo ./toolbox --version ``` -## Configure and run Toolbox - -This section will create a `tools.yaml` file, which will define which tools your AI Agent will have access to. You can add, remove, or edit tools as needed to make sure you have the best tools for your workflows. - -This will configure the following tools: - -1. **list_tables**: lists tables and descriptions -3. **execute_sql**: execute any SQL statement - -To configure Toolbox, run the following steps: - -1. Set the following environment variables: - - ```bash - # The IP address of the Postgres instance. - export POSTGRES_HOST="127.0.0.1" - - # The port of the Postgres instance. - export POSTGRES_PORT=5432 - - # The name of the database you want to connect to within the instance. - export POSTGRES_DB="your-database-name" - - # The username for connecting to the database. - export POSTGRES_USER="your-database-user" - - # The password for the specified database user. - export POSTGRES_PASS="your-database-password" - ``` - -2. Create a `tools.yaml` file. - -3. Copy and paste the following contents into the `tools.yaml`: - - ```yaml - sources: - postgresql-source: - kind: postgres - host: ${POSTGRES_HOST} - port: ${POSTGRES_PORT} - database: ${POSTGRES_DB} - user: ${POSTGRES_USER} - password: ${POSTGRES_PASS} - - tools: - execute_sql: - kind: postgres-execute-sql - source: postgresql-source - description: Use this tool to execute SQL. - - - list_tables: - kind: postgres-sql - source: postgresql-source - description: "Lists detailed schema information (object type, columns, constraints, indexes, triggers, owner, comment) as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. If names are omitted, lists all tables in user schemas." - statement: | - WITH desired_relkinds AS ( - SELECT ARRAY['r', 'p']::char[] AS kinds -- Always consider both 'TABLE' and 'PARTITIONED TABLE' - ), - table_info AS ( - SELECT - t.oid AS table_oid, - ns.nspname AS schema_name, - t.relname AS table_name, - pg_get_userbyid(t.relowner) AS table_owner, - obj_description(t.oid, 'pg_class') AS table_comment, - t.relkind AS object_kind - FROM - pg_class t - JOIN - pg_namespace ns ON ns.oid = t.relnamespace - CROSS JOIN desired_relkinds dk - WHERE - t.relkind = ANY(dk.kinds) -- Filter by selected table relkinds ('r', 'p') - AND (NULLIF(TRIM($1), '') IS NULL OR t.relname = ANY(string_to_array($1,','))) -- $1 is object_names - AND ns.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast') - AND ns.nspname NOT LIKE 'pg_temp_%' AND ns.nspname NOT LIKE 'pg_toast_temp_%' - ), - columns_info AS ( - SELECT - att.attrelid AS table_oid, att.attname AS column_name, format_type(att.atttypid, att.atttypmod) AS data_type, - att.attnum AS column_ordinal_position, att.attnotnull AS is_not_nullable, - pg_get_expr(ad.adbin, ad.adrelid) AS column_default, col_description(att.attrelid, att.attnum) AS column_comment - FROM pg_attribute att LEFT JOIN pg_attrdef ad ON att.attrelid = ad.adrelid AND att.attnum = ad.adnum - JOIN table_info ti ON att.attrelid = ti.table_oid WHERE att.attnum > 0 AND NOT att.attisdropped - ), - constraints_info AS ( - SELECT - con.conrelid AS table_oid, con.conname AS constraint_name, pg_get_constraintdef(con.oid) AS constraint_definition, - CASE con.contype WHEN 'p' THEN 'PRIMARY KEY' WHEN 'f' THEN 'FOREIGN KEY' WHEN 'u' THEN 'UNIQUE' WHEN 'c' THEN 'CHECK' ELSE con.contype::text END AS constraint_type, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = u.attnum) AS constraint_columns, - NULLIF(con.confrelid, 0)::regclass AS foreign_key_referenced_table, - (SELECT array_agg(att.attname ORDER BY u.attposition) FROM unnest(con.confkey) WITH ORDINALITY AS u(attnum, attposition) JOIN pg_attribute att ON att.attrelid = con.confrelid AND att.attnum = u.attnum WHERE con.contype = 'f') AS foreign_key_referenced_columns - FROM pg_constraint con JOIN table_info ti ON con.conrelid = ti.table_oid - ), - indexes_info AS ( - SELECT - idx.indrelid AS table_oid, ic.relname AS index_name, pg_get_indexdef(idx.indexrelid) AS index_definition, - idx.indisunique AS is_unique, idx.indisprimary AS is_primary, am.amname AS index_method, - (SELECT array_agg(att.attname ORDER BY u.ord) FROM unnest(idx.indkey::int[]) WITH ORDINALITY AS u(colidx, ord) LEFT JOIN pg_attribute att ON att.attrelid = idx.indrelid AND att.attnum = u.colidx WHERE u.colidx <> 0) AS index_columns - FROM pg_index idx JOIN pg_class ic ON ic.oid = idx.indexrelid JOIN pg_am am ON am.oid = ic.relam JOIN table_info ti ON idx.indrelid = ti.table_oid - ), - triggers_info AS ( - SELECT tg.tgrelid AS table_oid, tg.tgname AS trigger_name, pg_get_triggerdef(tg.oid) AS trigger_definition, tg.tgenabled AS trigger_enabled_state - FROM pg_trigger tg JOIN table_info ti ON tg.tgrelid = ti.table_oid WHERE NOT tg.tgisinternal - ) - SELECT - ti.schema_name, - ti.table_name AS object_name, - json_build_object( - 'schema_name', ti.schema_name, - 'object_name', ti.table_name, - 'object_type', CASE ti.object_kind - WHEN 'r' THEN 'TABLE' - WHEN 'p' THEN 'PARTITIONED TABLE' - ELSE ti.object_kind::text -- Should not happen due to WHERE clause - END, - 'owner', ti.table_owner, - 'comment', ti.table_comment, - 'columns', COALESCE((SELECT json_agg(json_build_object('column_name',ci.column_name,'data_type',ci.data_type,'ordinal_position',ci.column_ordinal_position,'is_not_nullable',ci.is_not_nullable,'column_default',ci.column_default,'column_comment',ci.column_comment) ORDER BY ci.column_ordinal_position) FROM columns_info ci WHERE ci.table_oid = ti.table_oid), '[]'::json), - 'constraints', COALESCE((SELECT json_agg(json_build_object('constraint_name',cons.constraint_name,'constraint_type',cons.constraint_type,'constraint_definition',cons.constraint_definition,'constraint_columns',cons.constraint_columns,'foreign_key_referenced_table',cons.foreign_key_referenced_table,'foreign_key_referenced_columns',cons.foreign_key_referenced_columns)) FROM constraints_info cons WHERE cons.table_oid = ti.table_oid), '[]'::json), - 'indexes', COALESCE((SELECT json_agg(json_build_object('index_name',ii.index_name,'index_definition',ii.index_definition,'is_unique',ii.is_unique,'is_primary',ii.is_primary,'index_method',ii.index_method,'index_columns',ii.index_columns)) FROM indexes_info ii WHERE ii.table_oid = ti.table_oid), '[]'::json), - 'triggers', COALESCE((SELECT json_agg(json_build_object('trigger_name',tri.trigger_name,'trigger_definition',tri.trigger_definition,'trigger_enabled_state',tri.trigger_enabled_state)) FROM triggers_info tri WHERE tri.table_oid = ti.table_oid), '[]'::json) - ) AS object_details - FROM table_info ti ORDER BY ti.schema_name, ti.table_name; - parameters: - - name: table_names - type: string - description: "Optional: A comma-separated list of table names. If empty, details for all tables in user-accessible schemas will be listed." - ``` - -4. Start Toolbox to listen on `127.0.0.1:5000`: - - ```bash - ./toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 - ``` - -{{< notice tip >}} -To stop the Toolbox server when you're finished, press `ctrl+c` to send the terminate signal. -{{< /notice >}} - ## Configure your MCP Client {{< tabpane text=true >}} {{% tab header="Claude code" lang="en" %}} 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). -2. Create a `.mcp.json` file in your project root if it doesn't exist. -3. Add the following configuration and save: +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } ``` -4. Restart Claude code to apply the new configuration. +1. Restart Claude code to apply the new configuration. {{% /tab %}} {{% tab header="Claude desktop" lang="en" %}} -1. Install [`npx`](https://docs.npmjs.com/cli/v8/commands/npx). -2. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. -3. Under the Developer tab, tap Edit Config to open the configuration file. -4. Add the following configuration and save: +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "http://127.0.0.1:5000/mcp/sse" - ] + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } ``` -5. Restart Claude desktop. -6. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. {{% /tab %}} {{% tab header="Cline" lang="en" %}} 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. -2. Tap Configure MCP Servers to open the configuration file. -3. Add the following configuration and save: +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } ``` -4. You should see a green active status after the server is successfully connected. +1. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Cursor" lang="en" %}} 1. Create a `.cursor` directory in your project root if it doesn't exist. -2. Create a `.cursor/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } ``` -4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Visual Studio Code (Copilot)" lang="en" %}} 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. -2. Create a `.vscode/mcp.json` file if it doesn't exist and open it. -3. Add the following configuration: +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "type": "sse", - "url": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } @@ -325,14 +214,22 @@ To stop the Toolbox server when you're finished, press `ctrl+c` to send the term {{% tab header="Windsurf" lang="en" %}} 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. -2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. -3. Add the following configuration: +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: ```json { "mcpServers": { "postgres": { - "serverUrl": "http://127.0.0.1:5000/mcp/sse" + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","postgres","--stdio"], + "env": { + "POSTGRES_HOST": "", + "POSTGRES_PORT": "", + "POSTGRES_DATABASE": "", + "POSTGRES_USER": "", + "POSTGRES_PASSWORD": "" + } } } } diff --git a/docs/en/how-to/connect-ide/spanner_mcp.md b/docs/en/how-to/connect-ide/spanner_mcp.md new file mode 100644 index 0000000000..89024c26ce --- /dev/null +++ b/docs/en/how-to/connect-ide/spanner_mcp.md @@ -0,0 +1,344 @@ +--- +title: "Spanner using MCP" +type: docs +weight: 2 +description: > + Connect your IDE to Spanner using Toolbox. +--- + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Spanner. This guide covers how to use [MCP Toolbox for Databases][toolbox] to expose your developer assistant tools to a Spanner instance: + +* [Cursor][cursor] +* [Windsurf][windsurf] (Codium) +* [Visual Studio Code ][vscode] (Copilot) +* [Cline][cline] (VS Code extension) +* [Claude desktop][claudedesktop] +* [Claude code][claudecode] + +[toolbox]: https://github.com/googleapis/genai-toolbox +[cursor]: #configure-your-mcp-client +[windsurf]: #configure-your-mcp-client +[vscode]: #configure-your-mcp-client +[cline]: #configure-your-mcp-client +[claudedesktop]: #configure-your-mcp-client +[claudecode]: #configure-your-mcp-client + +## Before you begin + +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. + +1. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project). + + +## Set up the database + +1. [Enable the Spanner API in the Google Cloud project](https://console.cloud.google.com/flows/enableapi?apiid=spanner.googleapis.com&redirect=https://console.cloud.google.com). + +1. [Create or select a Spanner instance and database](https://cloud.google.com/spanner/docs/create-query-database-console). + +1. Configure the required roles and permissions to complete this task. You will need [Cloud Spanner Database User](https://cloud.google.com/spanner/docs/iam#roles) role (`roles/spanner.databaseUser`) or equivalent IAM permissions to connect to the instance. + +1. Configured [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for your environment. + +## Install MCP Toolbox + +1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: + + + {{< tabpane persist=header >}} +{{< tab header="linux/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox +{{< /tab >}} + +{{< tab header="darwin/arm64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox +{{< /tab >}} + +{{< tab header="darwin/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox +{{< /tab >}} + +{{< tab header="windows/amd64" lang="bash" >}} +curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox +{{< /tab >}} +{{< /tabpane >}} + + + +1. Make the binary executable: + + ```bash + chmod +x toolbox + ``` + +1. Verify the installation: + + ```bash + ./toolbox --version + ``` + +## Configure your MCP Client + +{{< tabpane text=true >}} +{{% tab header="Claude code" lang="en" %}} + +1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). +1. Create a `.mcp.json` file in your project root if it doesn't exist. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" } + } + } + } + ``` + +1. Restart Claude code to apply the new configuration. +{{% /tab %}} + +{{% tab header="Claude desktop" lang="en" %}} + +1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. +1. Under the Developer tab, tap Edit Config to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + +1. Restart Claude desktop. +1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. +{{% /tab %}} + +{{% tab header="Cline" lang="en" %}} + +1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. +1. Tap Configure MCP Servers to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + +1. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Cursor" lang="en" %}} + +1. Create a `.cursor` directory in your project root if it doesn't exist. +1. Create a `.cursor/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + +1. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. +{{% /tab %}} + +{{% tab header="Visual Studio Code (Copilot)" lang="en" %}} + +1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn't exist. +1. Create a `.vscode/mcp.json` file if it doesn't exist and open it. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + +{{% /tab %}} + +{{% tab header="Windsurf" lang="en" %}} + +1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. +1. Tap on the hammer (MCP) icon, then Configure to open the configuration file. +1. Add the following configuration, replace the environment variables with your values, and save: + + Spanner with `googlesql` dialect + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + + Spanner with `postgresql` dialect + + ```json + { + "mcpServers": { + "spanner": { + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt","spanner-postgres","--stdio"], + "env": { + "SPANNER_PROJECT": "", + "SPANNER_INSTANCE": "", + "SPANNER_DATABASE": "" + } + } + } + } + ``` + +{{% /tab %}} +{{< /tabpane >}}