MCP Toolbox for Databases — Instalar & Demo en vivo

Por qué usarlo

Características clave

Un binario, múltiples motores: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
tools.yaml declarativo — cada herramienta es una sentencia nombrada y parametrizada, no una trampilla SQL de forma libre
Configuraciones precompiladas (--prebuilt postgres) para uso instantáneo sin configuración
Connection pooling y autenticación (IAM, OAuth, API key) gestionados centralmente, no en tu prompt
Transporte Stdio o HTTP/SSE — compatible con Claude Desktop, Cursor, Codex, IDEs y agentes personalizados
Reglas de autorización por herramienta — restringe quién puede llamar sentencias destructivas

Demo en vivo

Cómo se ve en la práctica

mcp-toolbox-databases.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: MCP Toolbox for Databases

Cómo dar a Claude acceso seguro de solo lectura a un Postgres de producción

👤 Ingenieros backend / de datos que quieren analítica con LLM sin riesgo de exfiltración ⏱ ~25 min intermediate

Cuándo usarlo: Quieres que Claude responda preguntas sobre una base de datos real sin una herramienta genérica execute_sql que pueda hacer DROP TABLE.

Requisitos previos

Postgres accesible via libpq URL — Usa un rol de solo lectura; nunca el usuario escribible de la app
Docker o Go instalado — Toolbox se distribuye como un único binario; la imagen Docker es la opción más sencilla

Flujo

Ejecutar Toolbox con el perfil postgres precompilado

Inicia mcp-toolbox en modo stdio usando --prebuilt postgres con POSTGRES_URL apuntando a la réplica de lectura.✓ Copiado

→ Toolbox registra tools registered: list_tables, describe_table, execute_sql_readonly
Conectarlo a Claude Desktop

Añade la configuración Docker de toolbox en claude_desktop_config.json bajo mcpServers, luego reinicia Claude.✓ Copiado

→ /mcp lista las herramientas de toolbox sin errores
Hacer una consulta real

Toolbox: lista las tablas. Para orders, ¿cuál es el valor mediano de pedido en los últimos 7 días? Muéstrame el SQL exacto que ejecutaste.✓ Copiado

→ Claude llama list_tables → describe_table → execute_sql_readonly con un SELECT (nunca UPDATE/DELETE)

Resultado: Analítica de solo lectura sobre datos reales sin riesgo de mutación, con registro de auditoría de cada consulta.

Errores comunes

Apuntar al usuario escribible — Claude eventualmente llama una herramienta mutante — Usa siempre un rol con GRANT SELECT únicamente; verifica con \du en psql
Pool de conexiones agotado bajo llamadas paralelas del agente — Configura pool.max_open_conns en tools.yaml; el valor por defecto es conservador

Combinar con: filesystem · github

Definir una herramienta analítica personalizada con validación de parámetros

👤 Equipos que no quieren SQL en bruto, solo consultas sancionadas ⏱ ~20 min intermediate

Cuándo usarlo: Quieres que Claude responda 'top 10 clientes este mes' pero que nunca invente sus propios JOINs.

Requisitos previos

Archivo tools.yaml — Crea en ~/.mcp-toolbox/tools.yaml

Flujo

Escribir una herramienta parametrizada

Añade una herramienta top_customers a tools.yaml: parámetro since: date, sentencia SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Copiado

→ Toolbox recarga y expone solo top_customers — sin execute_sql_readonly
Llamar desde Claude

Usa top_customers since=2026-04-01 y explica el resultado.✓ Copiado

→ Una sola llamada con parámetro de fecha validado, resultado formateado

Resultado: Superficie analítica cerrada — Claude no puede ejecutar nada que no hayas declarado.

Errores comunes

Olvidar eliminar la herramienta precompilada execute_sql — Elimina --prebuilt; carga solo tu tools.yaml

Explorar datasets de BigQuery sin escribir SQL

👤 Analistas en Google Cloud ⏱ ~20 min intermediate

Cuándo usarlo: Tienes un proyecto BigQuery y quieres que Claude responda preguntas con controles de costo.

Requisitos previos

Proyecto GCP + dataset — Ejecuta gcloud auth application-default login para que Toolbox tome las credenciales

Flujo

Iniciar Toolbox con --prebuilt bigquery

Ejecuta toolbox --prebuilt bigquery con PROJECT=my-proj.✓ Copiado

→ Herramientas bq_list_datasets, bq_dry_run, bq_query registradas
Siempre hacer dry-run primero

Antes de ejecutar cualquier consulta, llama bq_dry_run para estimar los bytes analizados. Si es > 1GB, pregúntame antes de ejecutar.✓ Copiado

→ Estimación de costo mostrada antes de la consulta facturable

Resultado: Respuestas de BigQuery con controles de costo — sin consultas sorpresa de $200.

Errores comunes

Discrepancia de ubicación por defecto (US vs EU) — Configura la variable de entorno BIGQUERY_LOCATION

Consultar múltiples bases de datos desde una sesión de Claude

👤 Ingenieros depurando problemas entre almacenes ⏱ ~30 min advanced

Cuándo usarlo: Los datos de pedidos están en Postgres, los eventos en BigQuery y la caché en Redis — necesitas correlación entre los tres.

Requisitos previos

tools.yaml con múltiples fuentes — Define cada fuente bajo sources: y etiqueta las herramientas con la fuente

Flujo

Conectar las tres fuentes

Añade postgres-prod, bq-events, redis-cache como fuentes en tools.yaml. Añade 1–2 herramientas por fuente.✓ Copiado

→ Toolbox arranca con todas las fuentes marcadas como healthy
Hacer una pregunta cross-store

Para el pedido 12345: extrae la fila de Postgres, la línea de tiempo de eventos de BigQuery y el estado actual de caché de Redis. Reconcilia.✓ Copiado

→ Tres llamadas en paralelo, una respuesta coherente

Resultado: Depuración cross-store sin tres herramientas separadas ni sesiones SSH.

Errores comunes

El health check de fuente falla silenciosamente — Ejecuta toolbox validate tools.yaml antes de arrancar

Combinar con: filesystem

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

mcp-toolbox-databases + filesystem

Extraer un resultado de consulta y guardarlo como CSV en tu workspace

Toolbox: top 100 pedidos esta semana. Filesystem: guarda como /tmp/orders.csv.✓ Copiado

mcp-toolbox-databases + github

Abrir un PR con una migración SQL después de que Claude proponga un cambio de schema

Toolbox: describe la tabla orders. GitHub: abre un PR añadiendo un índice en customer_id.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_tables	schema?: str	Primer paso de exploración	1 consulta
describe_table	table: str	Antes de escribir SQL sobre una tabla desconocida	1 consulta
execute_sql_readonly	sql: str	Analítica de forma libre sobre la réplica de lectura	1 consulta
bq_dry_run	sql: str	BigQuery: siempre antes de bq_query	gratis (dry run)
bq_query	sql: str	Después de que el dry run muestre un costo aceptable	facturable por bytes analizados
<tu-herramienta-personalizada>	depende de tools.yaml	Cualquier cosa que hayas declarado en tools.yaml	1 consulta

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguna — limitada por el límite de conexiones de tu BD
Tokens por llamada: 100–5000 según el tamaño del resultado
Monetario: OSS gratuito; la BD o nube subyacente se factura normalmente
Consejo: Limita las filas de resultado en tools.yaml (p. ej. LIMIT 200); para BigQuery siempre pasa por bq_dry_run primero

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: rol de BD de solo lectura

Almacenamiento de credenciales: Variables de entorno o Google ADC; Toolbox nunca persiste credenciales

Salida de datos: Conexión directa a la BD — sin salto a terceros. Toolbox es solo local.

No conceder nunca: DBA DROP/TRUNCATE en prod

Siempre antepón una réplica de lectura + rol de solo lectura a producción; nunca el usuario escribible de la app

Resolución de problemas

Errores comunes y soluciones

connection refused / pool exhausted

Aumenta pool.max_open_conns en tools.yaml; verifica el límite de conexiones de la BD

Verificar: psql, ejecuta SELECT count(*) FROM pg_stat_activity

tool not found

Con --prebuilt, el nombre de la herramienta es p. ej. pg_list_tables; comprueba con toolbox list-tools

BigQuery 403 access denied

Ejecuta gcloud auth application-default login y concede roles/bigquery.dataViewer

Verificar: bq ls

Errores de Spanner Cloud SDK

Configura GOOGLE_APPLICATION_CREDENTIALS apuntando a un JSON de cuenta de servicio

Alternativas

MCP Toolbox for Databases vs otros

Alternativa	Cuándo usarla	Contrapartida
DBHub	Quieres un único binario sin dependencias para Postgres/MySQL/SQL Server	Menos profundidad en BigQuery/Spanner, sin Google IAM
Postgres MCP (modelcontextprotocol)	Solo Postgres, sin configuración YAML	Menos restrictivo — expone execute_sql por defecto
MySQL MCP (benborla)	Solo MySQL, solo lectura	Motor único, más simple

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills