MCP Server for Spanner

By k65miyazakiy GitHub

mcp-server spanner

Overview

What is MCP Server for Spanner?

MCP Server for Spanner is a Model Context Protocol (MCP) server that connects to Google Cloud Spanner databases to execute SQL queries. It primarily serves as a tool for AI assistants to interact with Spanner databases.

How to use MCP Server for Spanner?

To use the MCP Server, clone the repository, install dependencies, and set up the server according to the provided instructions. It supports connection to the Spanner emulator.

Key features of MCP Server for Spanner?

Execute SELECT queries
Perform data updates (INSERT, UPDATE, DELETE)
Execute DDL queries (CREATE TABLE, ALTER TABLE, etc.)
Retrieve a list of tables
Display detailed table structures

Use cases of MCP Server for Spanner?

Enabling AI assistants to query and manipulate data in Spanner databases.
Facilitating database management tasks through SQL commands.
Supporting development and testing with the Spanner emulator.

FAQ from MCP Server for Spanner?

What are the prerequisites for using MCP Server for Spanner?

Node.js 22 or higher and access to a Spanner emulator or devcontainer environment are required.

Is there a specific setup for using the server with Claude Desktop?

Yes, specific configuration steps are provided for integrating with Claude Desktop.

What license is MCP Server for Spanner under?

It is licensed under the MIT license.

Content

MCP Server for Spanner

MCP Server for Spanner は、Google Cloud Spanner データベースに接続し、SQL クエリを実行するための Model Context Protocol (MCP) サーバーです。主に AI アシスタントなどが Spanner データベースとの対話を行うためのツールとして機能します。

機能

SELECT クエリの実行
データ更新 (INSERT, UPDATE, DELETE) クエリの実行
DDL (CREATE TABLE, ALTER TABLE など) クエリの実行
テーブル一覧の取得
テーブル構造の詳細表示

インストール

前提条件

Node.js 22 以上
Spanner エミュレータもしくは devcontainer を利用可能な環境

セットアップ

# リポジトリのクローン
git clone <repository-url>
cd mcp-server-spanner

# 依存関係のインストール
npm install

# TypeScriptのビルド
npm run build

注: 現在のところ、このツールは Spanner エミュレータへの接続のみをサポートしています。

使用方法

MCP サーバーの一般的な起動方法に準じます。ここでは、具体的な利用例として Claude Desktop での利用方法と、開発用の MCP Inspector を利用した方法を記載します。

Claude Desktop での設定方法（Mac/Linux）

Claude Desktop の設定より、次の設定の Spanner エミュレータの接続情報部分を編集し、追加します。

    "spanner": {
      "command": "bash",
      "args": [
        "YOUR_LOCAL_REPOSITORY_ROOT/bin/mcp-server-spanner",
        "--project-id=YOUR_PROJECT_ID",
        "--instance-id=YOUR_INSTANCE_ID",
        "--database-id=YOUR_DATABASE_ID",
        "--api-endpoint=localhost:9010"
      ],
    }

その後、Claude Desktop を再起動してください。

提供されるツール

MCP サーバーとして以下のツールを提供します:

read_query: SELECT クエリを実行
list_tables: データベースのテーブル一覧を取得
describe_table: 指定されたテーブルの構造を表示
execute_ddl: DDL クエリを実行
execute_write: 更新系 (INSERT, UPDATE, DELETE) クエリを実行

環境変数

環境変数	説明	デフォルト値
PROJECT_ID	Google Cloud Project ID	dev-project
INSTANCE_ID	Spanner Instance ID	dev-instance
DATABASE_ID	Spanner Database ID	dev-database
API_ENDPOINT	Spanner API エンドポイント (エミュレータ用)	spanner-emulator:9010
SPANNER_EMULATOR_HOST	Spanner エミュレータのホスト	(API_ENDPOINT から自動設定)

開発者向け情報

devcontainer での環境構築

本リポジトリは devcontainer での開発に対応しています。 VSCode で本リポジトリをクローン後、コンテナで開いてください。

devcontainer コンテナおよび Spanner エミュレータ、インスタンスおよびデータベースを自動で設定します。

インスペクタの使用

シェルから次のコマンドを実行します。

# MCPプロトコル形式でサーバーを起動
npm run inspect

使用する Spanner エミュレータのエンドポイントは環境変数で指定できます：

# 環境変数で接続情報を指定する例
export PROJECT_ID=your-project-id
export INSTANCE_ID=your-instance-id
export DATABASE_ID=your-database-id
export API_ENDPOINT=localhost:9010
npm run inspect