Google Cloud MCP Server Cursor IDE Setup 2026

Google doesn't ship one monolithic "GCP MCP server." What it ships instead is MCP Toolbox for Databases (the project formerly called genai-toolbox, renamed to align with MCP once it became clear that's what people were using it for) — a standalone server binary that connects to Cloud SQL, AlloyDB, Spanner, BigQuery, or Firestore based on a config file you write. This guide covers that toolbox: install the binary, describe your data source and the queries you want exposed as tools in tools.yaml, point Cursor at the running server, and you're set.

If you came here expecting a single npx command like some of the other guides on this site, the extra step is the tradeoff for scope — one toolbox binary can front any of Google's managed databases, but it needs to be told which database and which queries, because unlike a SaaS API there's no single fixed schema to introspect generically.

Prerequisites

Step 1: Install the Toolbox

Pick whichever install path fits your setup. The binary download (adjust the OS/arch and version as needed):

export VERSION=1.9.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Or via Homebrew:

brew install mcp-toolbox

Or skip the binary entirely and use the prebuilt npm wrapper for a quick single-database setup:

npx @toolbox-sdk/server --prebuilt=postgres --stdio

The --prebuilt flag ships ready-made tool definitions for common databases (Postgres, MySQL, and others) so you don't have to hand-write tools.yaml for a standard setup — connection details go in environment variables instead.

Step 2: Define Your Source and Tools (Custom Setup)

For anything beyond a quick prebuilt connection, write a tools.yaml. A source describes the database connection:

kind: source
name: my-cloudsql-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password

A tool describes a specific, named query the AI is allowed to run — this is the part that makes the toolbox safer than "give the AI raw SQL access":

kind: tool
name: search-orders-by-customer
type: postgres-sql
source: my-cloudsql-source
description: Find orders placed by a given customer email.
parameters:
  - name: email
    type: string
    description: The customer's email address.
statement: SELECT * FROM orders WHERE customer_email = $1;

Group related tools into a toolset if you want to load a subset at a time rather than everything in the file.

Step 3: Run the Server

./toolbox --config "tools.yaml"

Add --ui if you want a local interactive page for browsing and testing tools before wiring up Cursor:

./toolbox --config "tools.yaml" --ui

Step 4: Point Cursor at It

Add an HTTP-type entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

If you defined toolsets and only want one loaded, target it directly: "url": "http://127.0.0.1:5000/mcp/{toolset_name}".

Step 5: Restart Cursor and Verify

List the tools available from the toolbox MCP server, then run
search-orders-by-customer for someone@example.com.

Auth Notes for Cloud SQL, AlloyDB, and Spanner

The toolbox supports integrated IAM auth for Google's managed databases, letting you skip storing a database password in tools.yaml entirely in favor of your gcloud identity or a service account. This is worth setting up over static credentials if the toolbox is going to run anywhere other than a throwaway local environment — a tools.yaml with a plaintext password field is a real credential sitting in a config file, same risk as any other hardcoded secret.

When This Setup Breaks

Server starts but every tool call fails with a connection error. This is almost always the source config, not Cursor — confirm host, port, and credentials in tools.yaml actually work with a direct psql (or equivalent) connection before assuming the MCP layer is broken.

Prebuilt mode works but custom tools.yaml doesn't load. The prebuilt and custom-config paths are genuinely different code paths (env-var-driven vs. file-driven) — if you started with --prebuilt and are now migrating to a custom tools.yaml, don't assume settings carry over; the prebuilt config's environment variables aren't automatically reflected in your source block.

When NOT to use this MCP server: if you want an AI to run arbitrary, unplanned SQL against a database, this is the wrong tool by design — every tool in tools.yaml is a specific, pre-approved query with typed parameters, not an open SQL console. That constraint is a feature for production databases, but if you genuinely want ad hoc querying against a local dev database, a lighter-weight Postgres or MySQL MCP server without the tools.yaml layer will get you there faster.

Frequently Asked Questions

Q: Is this the official Google-maintained way to connect Cursor to Google Cloud databases?
A: Yes — MCP Toolbox for Databases is Google's open-source project (googleapis/mcp-toolbox on GitHub), formerly named genai-toolbox, renamed once its primary use case became MCP integration.

Q: Does one toolbox instance cover Cloud SQL, AlloyDB, Spanner, and BigQuery at the same time?
A: You can define multiple source blocks of different types in the same tools.yaml and expose tools against each, so yes — one running toolbox process can front several database types simultaneously if you configure them.

Q: Do I have to write tools.yaml by hand, or is there a faster path?
A: The --prebuilt flag (via the @toolbox-sdk/server npm package) ships ready-made tool sets for common databases like Postgres and MySQL, configured through environment variables instead of a YAML file. It's the faster path for a standard single-database setup; hand-written tools.yaml is for custom queries or multiple sources.

Q: Why does the toolbox require pre-defined tools instead of just letting the AI write SQL?
A: It's a deliberate safety boundary — every exposed tool is a specific, parameterized statement reviewed and approved ahead of time, not an open SQL interface. This matters more the closer the target database is to production; it trades some flexibility for not giving an AI agent unrestricted query access.

Q: Can I avoid putting a database password in tools.yaml?
A: Yes, for Google's managed databases — the toolbox supports integrated IAM auth for Cloud SQL, AlloyDB, and Spanner, letting the connection use your gcloud identity or a service account instead of a static password stored in the config file.

Related Guides

---