MCP Server Spanner

🚀 MCP Server for Spanner

The MCP Server for Spanner is a Model Context Protocol (MCP) server that connects to a Google Cloud Spanner database and executes SQL queries. It is primarily used for interactions between tools such as AI assistants and the Spanner database.

🚀 Quick Start

The MCP Server for Spanner serves as a bridge between AI - related tools and Google Cloud Spanner databases, enabling seamless data interaction and query execution.

✨ Features

• Execute SELECT queries.
• Execute data update (INSERT, UPDATE, DELETE) queries.
• Execute DDL (CREATE TABLE, ALTER TABLE, etc.) queries.
• Retrieve a list of tables.
• Display detailed structural information of a specified table.

📦 Installation

Prerequisites

• Node.js 22 or higher.
• An available Spanner emulator or a devcontainer environment.

Setup

# Clone the repository
git clone <repository-url>
cd mcp-server-spanner

# Install dependencies
npm install

# Build using TypeScript
npm run build

⚠️ Important Note

Currently, this tool only supports connecting to the Spanner emulator.

💻 Usage Examples

Basic Usage

The MCP server starts in the same way as usual. The following details the setup method in Claude Desktop and the method of using the development - oriented MCP Inspector.

Configuration on Claude Desktop (Mac/Linux)

From Claude Desktop settings, edit the part related to connecting to the Spanner emulator and add the following:

    "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"
      ],
    }

Then restart Claude Desktop.

Advanced Usage

The MCP server provides the following tools:

1. read_query: Execute a SELECT query.
2. list_tables: Retrieve a list of tables in the database.
3. describe_table: Display the structure of a specified table.
4. execute_ddl: Execute a DDL query.
5. execute_write: Execute an update operation (INSERT, UPDATE, DELETE).

📚 Documentation

Environment Variables

Developer Information

Building the Environment in a Devcontainer

This repository supports development in a devcontainer environment. Please clone this repository using VSCode and open the container within it. The devcontainer will automatically configure the Spanner emulator, instance, and database.

Using the Inspector

Run the following command in the shell:

# Start the server in MCP protocol format
npm run inspect

You can specify the information for connecting to the Spanner emulator through environment variables:

# Example of setting environment variables
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

📄 License

Please refer to the license file in the project repository.