Spanner Query AI Gateway - Read-Only MCP Server for Google Cloud Spanner

🌐 Revolutionizing Database Interaction for AI Agents

Spanner Query AI Gateway is not just another database connector—it's the read-only MCP (Model Context Protocol) server that transforms your Google Cloud Spanner into a secure, LLM-friendly knowledge source. Inspired by the original spanner-readonly-mcp, this project takes the concept to new heights, offering a production-grade, enterprise-ready solution for letting AI agents inspect schemas and execute SELECT queries without the risk of data mutation.

Think of it as a secure telescope for your Spanner data: LLMs can look, analyze, and reason, but they cannot touch. This is the ideal bridge for AI-driven analytics, schema exploration, and natural language querying on Google Cloud Spanner.

🧩 Key Features (Your Competitive Advantage)

Feature	Description	Emoji
Read-Only Enforcement	All write operations are blocked at the protocol level	🔒
LLM-Optimized Schema Inspection	Exposes table definitions, column types, indexes, and constraints	📋
Safe SELECT Query Execution	Supports parameterized queries with timeout and row limits	🛡️
Multi-Language Support	Works with OpenAI, Claude, Gemini, and custom LLMs	🌍
Responsive UI Dashboard	Monitor query logs, usage, and performance in real-time	📊
24/7 Customer Support	Built-in telemetry and alerting for production deployments	🕐
Cross-Platform Compatibility	Runs on Linux, macOS, and Windows	💻
Zero Data Leakage	Row-level security and column masking for sensitive data	🛡️

📊 System Architecture (Mermaid Diagram)

graph TD
    A[LLM Agent] -->|MCP Protocol| B[Spanner Query AI Gateway]
    B -->|Inspect Schema| C[Google Cloud Spanner]
    B -->|Execute SELECT| C
    B -->|No Write Ops| D[Blocked Operations]
    D -->|403 Forbidden| A
    
    B -->|Logging & Metrics| E[Monitoring Dashboard]
    E -->|Alerts| F[24/7 Support Team]
    
    subgraph "Security Layer"
        G[Read-Only Enforcer]
        H[Query Validator]
        I[Row Limiter]
    end
    
    B --> G --> H --> I --> C

💻 Example Profile Configuration

Create a .env file or use environment variables:

# Spanner Query AI Gateway Configuration
SPANNER_PROJECT_ID=your-project-id
SPANNER_INSTANCE_ID=your-instance
SPANNER_DATABASE_ID=your-database
SPANNER_CREDENTIALS_PATH=/path/to/service-account-key.json

# Server Configuration
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_READ_ONLY=true

# Security
MAX_ROWS=1000
QUERY_TIMEOUT_SECONDS=30
ALLOWED_QUERY_TYPES=SELECT,SHOW,DESCRIBE,EXPLAIN
SENSITIVE_COLUMNS=email,password,ssn

# AI Integration
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

🚀 Example Console Invocation

Start the MCP server:

python spanner_query_ai_gateway.py \
    --project my-project \
    --instance my-spanner-instance \
    --database my-db \
    --port 8080 \
    --read-only

Then send queries via MCP protocol:

# Example MCP client request
import requests

payload = {
    "action": "query",
    "sql": "SELECT table_name, table_type FROM information_schema.tables WHERE table_catalog = ' '",
    "parameters": {}
}

response = requests.post("http://localhost:8080/mcp", json=payload)
print(response.json())

🖥️ OS Compatibility Table