convez.ai
MCP ServerIntegração & APIsIntermediário
nu0ma

Spanner Read-Only MCP Server

nu0ma/spanner-readonly-mcp

Acesso seguro a Spanner para LLMs com garantia read-only

Ver no GitHub
InicialPluginScore · de 0 a 100

Um servidor MCP read-only para Google Cloud Spanner que permite LLMs inspecionar schemas e executar queries SELECT de forma segura contra bancos de dados Spanner. Implementa proteção contra escrita em duas camadas: validação de sintaxe e transações snapshot read-only.

Instalação

$npx convez-ai nu0ma/spanner-readonly-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.0.13
Issues abertas
12
Contribuidores
3

Casos de uso

  • Explorar schemas de bancos Spanner via Claude
  • Executar análises e queries SELECT contra dados Spanner
  • Integrar dados Spanner em fluxos de IA sem risco de mutação

Veredito

MCP server bem arquitetado com proteção robusta contra writes (regex + transações snapshot). Ideal para cenários de análise e exploração segura de dados Spanner em pipelines de IA, mas requer setup GCP prévio e credenciais configuradas.

README

A tradução para o português deste README ainda está na fila.

spanner-readonly-mcp

English | 日本語

A read-only MCP server for Google Cloud Spanner. Lets LLMs safely inspect schemas and run SELECT queries against a Spanner database.

Prerequisites

gcloud auth application-default login

Environment Variables

The server reads these at runtime (the Claude Code plugin prompts for them on install and persists to settings.json; for other clients, set them in the MCP config's env block).

VariableRequiredDescription
SPANNER_PROJECTYesGCP project ID
SPANNER_INSTANCEYesSpanner instance ID
SPANNER_DATABASEYesSpanner database ID
SPANNER_EMULATOR_HOSTNohost:port to point at a local Spanner (127.0.0.1:15000 for Spanner Omni single-server, 127.0.0.1:9010 for the legacy emulator). Leave unset for production.

Usage

Claude Code Plugin

This repo doubles as a Claude Code plugin marketplace. Register it and install the plugin:

/plugin marketplace add nu0ma/spanner-readonly-mcp
/plugin install spanner-readonly-mcp@spanner-readonly-mcp

The plugin launches the server via npx -y spanner-readonly-mcp@latest. Claude Code will prompt for SPANNER_PROJECT, SPANNER_INSTANCE, and SPANNER_DATABASE on install and persist them to settings.json.

Claude Code (without the plugin)

Create .mcp.json at your project root:

{
  "mcpServers": {
    "spanner-readonly-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "spanner-readonly-mcp@latest"],
      "env": {
        "SPANNER_PROJECT": "my-project",
        "SPANNER_INSTANCE": "my-instance",
        "SPANNER_DATABASE": "my-database"
      }
    }
  }
}

Claude Code picks this up on session start and prompts to approve the server on first launch.

Tools

ToolDescription
list_tablesList all user tables in the database
describe_tableGet column definitions (type, nullability, ordinal position) for a table
list_indexesList indexes, optionally filtered by table
execute_queryExecute an arbitrary SELECT query

Read-Only Guarantee

Writes are blocked even if your IAM credentials have write permissions. Two layers enforce this:

  1. Application layer (UX, best-effort): A regex rejects common mutation keywords (INSERT, UPDATE, UPSERT, DELETE, MERGE, and DDL/DCL) before they reach Spanner. Its purpose is to give the agent a clear, fast error when it accidentally writes a mutation — not to act as a security boundary. Payloads can trivially be rewritten (comments, CTE wrapping, parenthesization) to slip past it.
  2. Transaction layer (authoritative): Every query runs inside a Spanner read-only snapshot transaction (database.getSnapshot()). The Snapshot class does not expose DML methods, and the Spanner backend rejects any mutation attempt within a read-only transaction. This is the real guarantee.

All snapshot queries (including the metadata tools) run with a 30-second gaxOptions.timeout to bound worst-case latency.

Error messages returned to clients are sanitized (first line only, prefixed REGEX_BLOCKED: or SPANNER_ERROR:) to avoid leaking stack traces or internal paths.

IAM least privilege

execute_query accepts arbitrary SELECT statements, including queries against information_schema and spanner_sys. To bound the read surface, grant only roles/spanner.databaseReader to the service account — do not rely on application-level filtering alone.

Development

pnpm install
pnpm build           # compile to dist/
pnpm dev             # run from source without building
pnpm test            # vitest, starts Spanner Omni via docker compose

Direct execution against a real Spanner instance (build first, then run):

pnpm build
SPANNER_PROJECT=my-project \
SPANNER_INSTANCE=my-instance \
SPANNER_DATABASE=my-database \
pnpm start

License

MIT

Ver o original no GitHub

Bom para

Relacionados