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 natural langsung dari IDE.

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 disederhanakan dan serangkaian keahlian 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 keterampilan yang tersedia, lihat keterampilan Spanner di GitHub.

Sebelum memulai

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

  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. Buat agar biner 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: Google Cloud Project ID.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek SQL Spanner. Menerima googlesql atau postgresql. Nilai defaultnya 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 agar 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 alihkan model agen ke Gemini.
3. Di direktori root project, buat folder bernama .gemini dan di dalamnya, buat file settings.json.
4. Tambahkan salah satu konfigurasi berikut berdasarkan dialek Spanner Anda dalam file settings.json.
5. Ganti variabel berikut dengan nilai Anda:
  • PROJECT_ID: Google Cloud Project ID 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: Google Cloud Project ID.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek SQL Spanner. Menerima googlesql atau postgresql. Nilai defaultnya 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: Google Cloud Project ID.
    • INSTANCE_NAME: Nama instance Spanner.
    • DATABASE_NAME: Nama database Spanner.
    • DIALECT_NAME: Dialek SQL Spanner. Menerima googlesql atau postgresql. Nilai defaultnya adalah googlesql jika tidak ditentukan.
  4. Opsional. Perbarui marketplace: 
    codex plugin marketplace upgrade data-agent-kit

Claude untuk Desktop


1. Buka Claude untuk Desktop, lalu buka Setelan.
2. Di tab Developer, klik Edit Config untuk membuka file konfigurasi.
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. Mulai ulang Claude untuk Desktop.
5. Layar chat baru menampilkan ikon palu (MCP) dengan server MCP baru.

Cline


1. Buka ekstensi Cline di VS Code, lalu klik ikon MCP Servers.
2. Ketuk Configure MCP Servers untuk membuka file konfigurasi.
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"
      }
    }
  }
}

Status aktif 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 tidak ada, lalu 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, lalu buka Setelan > Setelan Kursor > 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 tidak ada, lalu buka.
3. Tambahkan salah satu konfigurasi berikut berdasarkan dialek Spanner Anda, ganti variabel lingkungan dengan nilai Anda, lalu simpan file:

Spanner dengan dialek 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. Tambahkan salah satu konfigurasi berikut berdasarkan dialek Spanner Anda, ganti variabel lingkungan dengan nilai Anda, lalu 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"
      }
    }
  }
}

Terhubung 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, lalu pilih MCP Servers.
  3. Cari Spanner dalam daftar server yang tersedia, lalu 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 keahlian dari server tersebut 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, lalu 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, lalu 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 keahlian dari server Spanner akan tersedia untuk editor.

Ganti kode berikut:

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

Menghubungkan ke Spanner menggunakan Data Agent Kit

Google Cloud Data Agent Kit memungkinkan Anda mengelola database Spanner dan menjalankan kueri terhadap data Spanner di IDE atau agen coding pilihan Anda. Ekstensi Data Agent Kit berfungsi dengan Visual Studio Code dan IDE berbasis VS Code, serta plugin Data Agent Kit berfungsi dengan sejumlah agen coding populer, termasuk Claude Code dan Codex CLI.

Data Agent Kit menyediakan kemampuan penemuan dan eksplorasi data, sehingga Anda dapat mengajukan pertanyaan tentang data Spanner dalam bahasa alami. Hal ini membantu menghilangkan pengalihan konteks antara alat command line Spanner dan lingkungan pengembangan Anda.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan Data Agent Kit.