---
name: google_mcp_toolbox
description: "Use this skill to connect to Google MCP Toolbox for Databases. Triggers include: any database queries, SQL execution requests, data exploration tasks, schema discovery, or connecting to PostgreSQL/MySQL/Redis/MongoDB/BigQuery/Cloud SQL and other databases. This skill provides prebuilt generic tools for instant data exploration and a framework to build specialized AI tools for production agents with database access. When the user mentions database operations, data analysis, SQL queries, or connecting to data sources, use this skill."
metadata: { "builtin_skill_version": "1.0" }
---

> **Important:** Google MCP Toolbox must be installed and running before use.

# Google MCP Toolbox for Databases

## Overview

Google MCP Toolbox is an open-source Model Context Protocol (MCP) server that connects AI agents directly to enterprise databases. It provides two modes:

1. **Prebuilt Tools Mode**: Ready-to-use generic tools for instant data exploration
2. **Custom Tools Mode**: Build specialized, highly secure AI tools via `tools.yaml` configuration

## Prerequisites

### Installation

**Option 1: npm (Quick Start)**
```bash
npm install -g @toolbox-sdk/server
```

**Option 2: Homebrew (macOS/Linux)**
```bash
brew install mcp-toolbox
```

**Option 3: Binary Download**
```bash
# macOS Apple Silicon
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox

# Linux AMD64
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
```

**Option 4: Docker**
```bash
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:1.1.0
```

### Supported Databases

| Category | Databases |
|----------|-----------|
| Google Cloud | AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore |
| Relational | PostgreSQL, MySQL, SQL Server, Oracle |
| NoSQL | MongoDB, Redis, Elasticsearch, Couchbase |
| Distributed | CockroachDB, ClickHouse, Snowflake, Trino, Neo4j |

## Quick Start

### Start the Toolbox Server

**Using npx:**
```bash
npx @toolbox-sdk/server --config tools.yaml
```

**Using binary:**
```bash
./toolbox --config tools.yaml
```

**Using Docker:**
```bash
docker run -p 5000:5000 \
  -v $(pwd)/tools.yaml:/app/tools.yaml \
  us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:1.1.0 \
  --config "/app/tools.yaml"
```

### Connect to MCP Toolbox

Add to your MCP client configuration (`mcp.json` or similar):

```json
{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

## Configuration

### tools.yaml Structure

```yaml
# Data Source Definition
kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: mydb
user: myuser
password: mypassword

# Tool Definition
kind: tool
name: search_users
type: postgres-sql
source: my-pg-source
description: Search for users by name
parameters:
  - name: name
    type: string
    description: The user's name
statement: SELECT * FROM users WHERE name ILIKE '%' || $1 || '%';

# Toolset Definition
kind: toolset
name: user_management
tools:
  - search_users
```

### Prebuilt Database Tools

When running with `--prebuilt=<database>`, these tools are available:

| Tool | Description |
|------|-------------|
| `list_tables` | List all tables in the database |
| `describe_table` | Get table schema and columns |
| `execute_sql` | Execute SQL query |
| `list_databases` | List available databases |

**Example:**
```bash
npx @toolbox-sdk/server --prebuilt=postgres
```

## Python SDK Usage

### Install Core SDK
```bash
pip install toolbox-core
```

### Load Tools in Python
```python
from toolbox_core import ToolboxClient

async with ToolboxClient("http://127.0.0.1:5000") as client:
    tools = await client.load_toolset("my_toolset")
```

## MCP Server API

### HTTP Endpoint
```
POST http://127.0.0.1:5000/mcp
```

### Request Format
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "statement": "SELECT * FROM users LIMIT 10"
    }
  }
}
```

### Response Format
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"rows\": [...], \"row_count\": 10}"
      }
    ]
  }
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `TOOLBOX_CONFIG` | Path to tools.yaml |
| `TOOLBOX_TELEMETRY_OTLP` | OTLP endpoint for telemetry |
| Database-specific | `PGPASSWORD`, `MYSQL_PASSWORD`, etc. |

## Security Features

- **Restricted Access**: Tools run with limited database permissions
- **Structured Queries**: Parameterized queries prevent SQL injection
- **IAM Integration**: Google Cloud authentication support
- **OpenTelemetry**: End-to-end observability and tracing

## Troubleshooting

- Server not responding? Check if port 5000 is available
- Auth failures? Verify database credentials in tools.yaml
- Tool not found? Ensure the toolset is loaded correctly
- Connection pooling issues? Adjust pool size in configuration

## More Information

- GitHub: https://github.com/googleapis/mcp-toolbox
- Documentation: https://github.com/googleapis/mcp-toolbox/blob/main/README.md
- SDKs: Python, JavaScript/TypeScript, Go
