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 mengabstraksi kebutuhan untuk menyiapkan koneksi server terpisah. 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 dan serangkaian alat, selain memberikan informasi mendetail tentang contoh penginstalan, konfigurasi, dan penggunaan. Jika menggunakan ekstensi Gemini CLI, Anda tidak perlu menginstal MCP Toolbox. Untuk mengetahui informasi selengkapnya, lihat Ekstensi Gemini CLI - Spanner.

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

Alat Contoh perintah natural language
list_tables Tabel apa yang ada di instance Spanner saya?
execute_sql Sisipkan data pengujian ke dalam tabel produk.
execute_sql_dql Produk apa di kategori elektronik yang dijual di Amerika?

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 versi terbaru MCP Toolbox sebagai biner. Pilih 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 alat agen

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

Gemini CLI

  1. Instal Gemini CLI.
  2. Instal ekstensi Spanner untuk Gemini CLI dari repositori GitHub menggunakan perintah berikut:
    3.   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 project Anda Google Cloud .
    • INSTANCE_NAME: nama instance Spanner Anda.
    • DATABASE_NAME: nama database Spanner Anda.
    • DIALECT_NAME: dialek Spanner SQL Anda. Menerima googlesql atau postgresql. Secara default ditetapkan ke googlesql jika tidak ditentukan.
  4. Mulai Gemini CLI dalam mode interaktif: 
        gemini
    CLI akan otomatis memuat ekstensi Spanner untuk Gemini CLI dan alatnya, yang dapat Anda gunakan untuk berinteraksi dengan database.

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, 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 project Anda Google Cloud .
  • 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. Buat file .mcp.json di root project Anda, jika belum ada.
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"
      }
    }
  }
}

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.

Cursor


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 Cursor 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 mengotorisasi Antigravity agar dapat 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 alat 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 alat dari server Spanner akan tersedia untuk editor.

Ganti kode berikut:

  • PROJECT_ID: ID project Anda Google Cloud .
  • 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, defaultnya adalah googlesql.