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 サーバーとして以下のツールを提供します:

1. read_query: SELECT クエリを実行
2. list_tables: データベースのテーブル一覧を取得
3. describe_table: 指定されたテーブルの構造を表示
4. execute_ddl: DDL クエリを実行
5. 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

ライセンス

MIT