DBeast

---

DBeast conecta asistentes de IA como Claude, Cursor, Windsurf y VS Code Copilot con PostgreSQL a través del Model Context Protocol. En lugar de exponer una amplia vía de escape execute_sql, DBeast proporciona 21 herramientas enfocadas para descubrimiento de esquemas, ejecución segura de consultas, análisis de impacto, revisión de rendimiento, comprobaciones de seguridad, informes de mantenimiento, monitoreo de replicación e inspección de calidad de datos.

---

Demo

Observa a Claude usar las herramientas MCP de DBeast para auditar una base de datos PostgreSQL, identificar riesgos de seguridad y mantenimiento, y previsualizar el impacto de la limpieza sin ejecutar SQL destructivo.

---

Cómo Funciona

AI assistant  --MCP stdio-->  DBeast server  --asyncpg-->  PostgreSQL
Claude/Cursor                  Python local                 Local, RDS,
Windsurf/VS Code               subprocess                   Supabase, Neon

DBeast se ejecuta como un servidor MCP local de stdio. Tu IDE o asistente de escritorio lo inicia como subproceso y pasa las credenciales de la base de datos a través de variables de entorno. El asistente llama a las herramientas de DBeast, DBeast consulta PostgreSQL y los resultados estructurados vuelven al asistente. No se requiere servicio HTTP ni infraestructura adicional.

---

Inicio Rápido

1. Instalar

git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .

Para desarrollo:

pip install -e ".[dev]"

Opcional: copia .env.example a .env y configura tus credenciales de base de datos.

2. Verificar

dbeast

O ejecuta el punto de entrada del código fuente directamente:

python src/server.py

3. Configurar Tu Cliente MCP

Configuración mínima para Cursor o Windsurf:

{
  "mcpServers": {
    "dbeast": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/DBeast/src/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Ubicaciones comunes de configuración:

Cliente	Ubicación de configuración
Cursor	.mcp.json en la raíz del proyecto, o ~/.cursor/.mcp.json globalmente
VS Code	.vscode/settings.json o configuración de usuario con la clave mcp.servers
Claude Desktop en macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop en Windows	%APPDATA%\Claude\claude_desktop_config.json
Windsurf	.mcp.json

Consulta SETUP.md para ejemplos completos de clientes, Docker, RDS, Supabase, Neon, túneles SSH, AWS Secrets Manager y solución de problemas.

4. Hacer Preguntas Simples o Complejas

Una vez conectado, tu asistente puede responder preguntas rápidas de búsqueda y también realizar investigaciones de bases de datos en varios pasos.

Ejemplos simples:

Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.

Ejemplos más complejos:

Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.

---

Herramientas

DBeast expone 21 herramientas MCP en 10 categorías.

Conexión

Herramienta	Descripción
connect	Conectarse a PostgreSQL, verificar el estado actual o descubrir bases de datos locales
disconnect	Cerrar la conexión actual a la base de datos
health_check	Verificar conectividad, salud del pool, versión de PostgreSQL y extensiones

Descubrimiento de Esquemas

Herramienta	Descripción
get_schema	Listar esquemas, tablas, columnas, índices, relaciones y diagramas ERD opcionales en Mermaid
dependency_analysis	Mapear dependencias de objetos antes de renombrar, eliminar o cambiar objetos de la base de datos

Acceso a Datos

Herramienta	Descripción
execute_query	Ejecutar consultas SELECT de solo lectura con inyección automática de límite de filas

Análisis de Consultas

Herramienta	Descripción
analyze_query	Analizar e inspeccionar la estructura de consultas, advertencias y sugerencias de optimización
query_optimizer	Recomendar índices y reescrituras para una consulta dada
analyze_impact	Previsualizar el impacto de consultas de escritura, nivel de riesgo, filas afectadas y contexto de reversión sin ejecutar

Salud de la Base de Datos

Herramienta	Descripción
database_health	Revisar tasas de acierto de caché, conexiones, antigüedad de transacciones, salud de tablas y señales generales de salud
query_performance	Informar consultas lentas o costosas a partir de las estadísticas de PostgreSQL

Seguridad

Herramienta	Descripción
security_audit	Inspeccionar roles, privilegios, cuentas de superusuario y exposición del esquema público
sensitive_data_scan	Detectar posibles PII o secretos mediante nombres de columnas y patrones de esquema

Mantenimiento

Herramienta	Descripción
maintenance_analysis	Revisar estado de vacuum, tuplas muertas, marcas de tiempo de analyze y salud de índices
partition_analysis	Inspeccionar salud de particiones, distribución de filas y riesgos de particiones faltantes

Calidad de Datos

Herramienta	Descripción
data_quality_report	Analizar tasas de nulos, cardinalidad, distribuciones de valores y valores atípicos
duplicate_detection	Encontrar filas duplicadas en columnas clave seleccionadas

Configuración del Servidor

Herramienta	Descripción
configuration_review	Revisar configuración de PostgreSQL y oportunidades de ajuste
replication_status	Inspeccionar retraso de replicación, estado de WAL emisor/receptor y slots de replicación

Auditoría

Herramienta	Descripción
get_audit_logs	Recuperar llamadas de herramientas MCP registradas para una fecha dada
list_audit_files	Listar archivos de registro de auditoría disponibles

---

Flujo de Trabajo Recomendado

Comienza descubriendo esquemas:

get_schema()
get_schema(schema='public')

Ejecuta consultas seguras de solo lectura:

execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')

Previsualiza escrituras riesgosas:

analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')

Verifica salud y mantenimiento:

database_health()
maintenance_analysis(schema='public')
query_performance()

La mayoría de las herramientas de análisis aceptan un parámetro schema:

maintenance_analysis(schema='public')  -> analyze one schema
maintenance_analysis(schema='all')     -> analyze every schema
get_schema(format='mermaid')           -> generate an ERD diagram

---

Bases de Datos Soportadas

Proveedor	Método de conexión
PostgreSQL local	DATABASE_URL o variables DB_* individuales
PostgreSQL en Docker	Variables explícitas o connect(discover=true)
AWS RDS / Aurora	URL directa, túnel SSH o AWS Secrets Manager
Supabase	Cadena de conexión del pooler desde la configuración del Dashboard
Neon	Cadena de conexión desde los detalles de conexión de la Consola
Railway / Render / Fly.io	Cadena de conexión del proveedor
Cualquier host PostgreSQL	URL estándar de PostgreSQL

---

Configuración

Elige un método de conexión.

# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db

# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer

# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2

También puedes conectarte en tiempo de ejecución:

connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')

Ajustes clave:

Variable	Predeterminado	Descripción
DBEAST_DEFAULT_ROW_LIMIT	100	Máximo de filas devueltas por execute_query
DBEAST_QUERY_TIMEOUT	300	Tiempo de espera de ejecución de consultas en segundos
DBEAST_COMMAND_TIMEOUT	300	Tiempo de espera del comando SQL en segundos
DBEAST_SSL_VERIFY	true	Establecer false para túneles SSH donde los certificados no coinciden con localhost
DBEAST_SCHEMA_CACHE_TTL	60	TTL de caché de esquema en segundos, 0 desactiva el caché
DBEAST_AUDIT_ENABLED	true	Registrar llamadas de herramientas MCP
DBEAST_AUDIT_DIR	logs/mcp_audit	Directorio de registros de auditoría

Consulta SETUP.md para la referencia completa de configuración.

---

Modelo de Seguridad

Tipo de consulta	Qué hace DBeast
SELECT	Ejecuta con límites automáticos de filas
INSERT / UPDATE / DELETE	Nunca se ejecuta; devuelve una vista previa de impacto
DROP / TRUNCATE	Nunca se ejecuta; informa objetos afectados y riesgo

Las respuestas formateadas y JSON usan un envoltorio consistente:

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "connected": true,
    "source": "tool"
  }
}

---

Registro de Auditoría

DBeast registra llamadas de herramientas MCP para responsabilidad y depuración.

DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_audit

Los archivos de auditoría se almacenan como archivos markdown diarios e incluyen marcas de tiempo, nombres de herramientas, duraciones, parámetros enmascarados, respuestas truncadas y errores.

---

Desarrollo

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/

Inicia la base de datos PostgreSQL de prueba local opcional:

docker compose up -d postgres

Compose heredado:

docker-compose up -d postgres

---

Documentación

• SETUP.md - Configuración completa del cliente, escenarios de conexión, configuración y solución de problemas
• CONTRIBUTING.md - Configuración de desarrollo, pruebas, estilo, commits y proceso de PR
• CODE_OF_CONDUCT.md - Directrices de la comunidad

---

Licencia

MIT