Menggunakan Spanner dengan MCP Toolbox for Databases, Gemini CLI, dan agen lainnya

Dokumen ini menjelaskan cara menghubungkan instance Spanner Anda ke berbagai alat developer yang mendukung Model Context Protocol (MCP).

Sebaiknya gunakan ekstensi Spanner khusus untuk Gemini CLI. Ekstensi ini menggabungkan kemampuan dasar langsung ke dalam ekstensi, yang menyederhanakan penyiapan dan konfigurasi. Anda dapat mengonfigurasi Gemini Code Assist untuk menggunakan Gemini CLI, yang menawarkan manfaat penyiapan serupa di IDE Anda. Untuk mengetahui informasi selengkapnya, lihat Ekstensi Gemini CLI - Spanner.

Atau, IDE dan alat developer lain yang mendukung MCP dapat terhubung melalui MCP Toolbox for Databases. MCP Toolbox adalah server MCP open source yang dirancang untuk menghubungkan agen AI ke data Anda. Alat ini menangani tugas seperti autentikasi dan penggabungan koneksi, sehingga Anda dapat berinteraksi dengan data menggunakan bahasa alami langsung dari IDE Anda.

Menggunakan ekstensi Gemini CLI di Spanner

Integrasi Spanner dengan Gemini CLI dilakukan melalui ekstensi open source yang menawarkan kemampuan tambahan dibandingkan dengan koneksi MCP Toolbox standar. Ekstensi ini menawarkan proses penginstalan yang efisien dan serangkaian kemampuan berdasarkan Alat MCP. Jika menggunakan ekstensi Gemini CLI, Anda tidak perlu menginstal MCP Toolbox. Untuk mengetahui informasi selengkapnya, lihat Ekstensi Gemini CLI - Spanner.

Ekstensi spanner mencakup kemampuan untuk mencantumkan tabel, dan menjalankan pernyataan SQL dan SQL DQL.

Untuk semua kemampuan yang tersedia, lihat kemampuan Spanner di GitHub.

Sebelum memulai

  1. Di Google Cloud konsol, pada halaman pemilih project, pilih atau buat Google Cloud project.

  2. Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

Menyiapkan instance Spanner

  1. Aktifkan Spanner API di Google Cloud project.

  2. Buat atau pilih instance dan database Spanner.

  3. Konfigurasi peran dan izin yang diperlukan untuk menyelesaikan tugas ini. Pengguna yang memanggil agen LLM memerlukan peran berikut di tingkat database:

    • Cloud Spanner Database Reader (roles/spanner.databaseReader) untuk menjalankan kueri DQL dan mencantumkan tabel.

    • Cloud Spanner Database User (roles/spanner.databaseUser) untuk menjalankan kueri DML.

  4. Konfigurasi Kredensial Default Aplikasi (ADC) untuk lingkungan Anda.

Menginstal MCP Toolbox

  1. Download MCP Toolbox versi terbaru sebagai program biner. Pilih program biner yang sesuai dengan sistem operasi (OS) dan arsitektur CPU Anda. Anda harus menggunakan MCP Toolbox versi 0.15.0 atau yang lebih baru:

    linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/windows/amd64/toolbox

  2. Jadikan biner sebagai file yang dapat dieksekusi:

    chmod +x toolbox

  3. Verifikasi penginstalannya:

    ./toolbox --version

Menyiapkan klien dan koneksi

Bagian ini menjelaskan cara mengonfigurasi berbagai alat developer untuk terhubung ke instance Spanner Anda. Pilih klien Anda dari opsi berikut:

Gemini CLI

  1. Instal Gemini CLI.
  2. Instal ekstensi Spanner untuk Gemini CLI dari repositori GitHub menggunakan perintah berikut: 
    gemini extensions install https://github.com/gemini-cli-extensions/spanner
  3. Tetapkan variabel lingkungan berikut untuk terhubung ke instance Spanner Anda: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Ganti kode berikut:
    • PROJECT_ID: ID Google Cloud project.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek Spanner SQL. Menerima googlesql atau postgresql. Secara default, nilainya adalah googlesql jika tidak ditentukan.
  4. Mulai Gemini CLI dalam mode interaktif: 
    gemini

    CLI akan otomatis memuat ekstensi Spanner untuk Gemini CLI dan kemampuannya, yang dapat Anda gunakan untuk berinteraksi dengan database Anda.

    Di Gemini CLI, gunakan perintah /extensions untuk memverifikasi bahwa ekstensi telah diinstal.

Gemini Code Assist

Sebaiknya konfigurasi Gemini Code Assist untuk menggunakan Gemini CLI, karena pendekatan ini menghilangkan kebutuhan untuk mengonfigurasi server MCP secara manual. Namun, petunjuk untuk mengonfigurasi server MCP secara manual masih tersedia di bagian berikut:


1. Instal ekstensi Gemini Code Assist di VS Code.
2. Aktifkan mode agen dan ganti model agen ke Gemini.
3. Di direktori utama project Anda, buat folder bernama .gemini dan, di dalamnya, buat file settings.json.
4. Tambahkan salah satu konfigurasi berikut berdasarkan dialek Spanner Anda di file settings.json.
5. Ganti variabel berikut dengan nilai Anda:
  • PROJECT_ID: ID Google Cloud project Anda.
  • INSTANCE_NAME: nama instance Spanner Anda.
  • DATABASE_NAME: nama database Spanner Anda.
6. Simpan file.

Spanner dengan dialek GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code

  1. Instal Claude Code.
  2. Tetapkan variabel lingkungan untuk terhubung ke instance Spanner Anda: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Ganti kode berikut:
    • PROJECT_ID: ID Google Cloud project.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek Spanner SQL. Menerima googlesql atau postgresql. Secara default, nilainya adalah googlesql jika tidak ditentukan.
  3. Mulai agen: 
    claude
  4. Instal plugin: 
    /plugin install spanner@claude-plugins-official

Codex

  1. Instal marketplace Data Agent Kit: 
    codex plugin marketplace add GoogleCloudPlatform/data-agent-kit
  2. Instal plugin Spanner: 
    codex plugin install spanner@data-agent-kit
  3. Konfigurasi variabel lingkungan untuk terhubung ke instance Spanner Anda: 
    export SPANNER_PROJECT="PROJECT_ID"
export SPANNER_INSTANCE="INSTANCE_NAME"
export SPANNER_DATABASE="DATABASE_NAME"
export SPANNER_DIALECT="DIALECT_NAME"
     Ganti kode berikut:
    • PROJECT_ID: ID Google Cloud project.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek Spanner SQL. Menerima googlesql atau postgresql. Secara default, nilainya adalah googlesql jika tidak ditentukan.
  4. Opsional. Perbarui marketplace: 
    codex plugin marketplace upgrade data-agent-kit

Claude for Desktop


1. Buka Claude for Desktop dan buka Settings.
2. Di tab Developer, klik Edit Config untuk membuka file konfigurasi.
3. GoogleSQL



{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Mulai ulang Claude for Desktop.
5. Layar chat baru menampilkan ikon palu (MCP) dengan server MCP baru.

Cline


1. Buka ekstensi Cline di VS Code dan klik ikon MCP Servers.
2. Ketuk Configure MCP Servers untuk membuka file konfigurasi.
3. GoogleSQL



{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Status aktif berwarna hijau akan muncul setelah server berhasil terhubung.

Kursor


1. Buat direktori .cursor di root project Anda jika belum ada.
2. Buat file .cursor/mcp.json jika belum ada dan buka.
3. Tambahkan salah satu konfigurasi berikut berdasarkan dialek Spanner Anda, ganti variabel lingkungan dengan nilai Anda, dan simpan file:

Spanner dengan dialek GoogleSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Buka Kursor dan buka Settings > Cursor Settings > MCP. Status aktif berwarna hijau akan muncul saat server terhubung.

Visual Studio Code (Copilot)


1. Buka VS Code dan buat direktori .vscode di root project Anda jika belum ada.
2. Buat file .vscode/mcp.json jika belum ada, lalu buka.
3. GoogleSQL



{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Windsurf


1. Buka Windsurf dan buka asisten Cascade.
2. Klik ikon MCP, lalu klik Configure untuk membuka file konfigurasi.
3. GoogleSQL



{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Spanner dengan dialek PostgreSQL: 

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Menghubungkan dengan Antigravity

Anda dapat menghubungkan Spanner ke Antigravity dengan cara berikut:

  • Menggunakan MCP Store
  • Menggunakan konfigurasi kustom

MCP Store

Cara yang paling direkomendasikan untuk terhubung ke Antigravity adalah dengan menggunakan MCP Store bawaan.

  1. Buka Antigravity dan buka panel agen editor.
  2. Klik ikon Menu di bagian atas panel dan pilih MCP Servers.
  3. Temukan Spanner dalam daftar server yang tersedia dan klik Install.
  4. Ikuti langkah-langkah di layar untuk mengizinkan Antigravity mengakses Project Google Cloud Anda. Tindakan ini memungkinkan Antigravity mengakses instance Spanner di project Anda.

Setelah Anda menginstal server Spanner di MCP Store, resource dan kemampuan dari server akan tersedia untuk editor.

Konfigurasi kustom

Untuk terhubung ke server MCP kustom, lakukan langkah-langkah berikut:

  1. Buka Antigravity dan buka panel agen editor.
  2. Klik ikon Menu di bagian atas panel dan pilih MCP Servers.
  3. Klik Manage MCP Servers > View raw config untuk membuka file mcp_config.json.
  4. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, dan simpan.
{
  "mcpServers": {
    "spanner": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME",
          "SPANNER_DIALECT": "DIALECT_NAME"
      }
    }
  }
}

Setelah Anda mengonfigurasi server MCP kustom, resource dan kemampuan dari server Spanner akan tersedia untuk editor.

Ganti kode berikut:

  • PROJECT_ID: ID Google Cloud project Anda.
  • INSTANCE_NAME: nama instance Spanner Anda.
  • DATABASE_NAME: nama database Spanner Anda.
  • DIALECT_NAME: dialek Spanner SQL Anda. Menerima googlesql atau postgresql. Jika Anda tidak menentukan dialek, nilai defaultnya adalah googlesql.

Menghubungkan ke Spanner di VS Code menggunakan ekstensi Data Agent Kit

Ekstensi Google Cloud Data Agent Kit memungkinkan Anda mengelola database Spanner dan menjalankan kueri terhadap data Spanner di IDE pilihan Anda. Visual Studio Code dan semua IDE yang didasarkan pada VS Code didukung.

Ekstensi ini menyediakan kemampuan penemuan dan eksplorasi data, sehingga Anda dapat mengajukan pertanyaan tentang data Spanner Anda dalam bahasa alami. Ekstensi ini membantu menghilangkan peralihan konteks antara alat command line Spanner dan lingkungan pengembangan Anda. Data Agent Kit juga menyediakan plugin CLI untuk digunakan dengan Google Cloud resource Anda.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan ekstensi Data Agent Kit untuk VS Code.