Neon MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Ramas de copia en escritura instantáneas — perfectas para probar migraciones
Gestión de proyectos, ramas, roles y bases de datos
Ejecuta SQL en cualquier rama (lectura o escritura)
Recuperación de cadenas de conexión para cualquier rama
Nativo: construido y mantenido por Neon

Demo en vivo

Cómo se ve en la práctica

neon.replay ▶ listo

0/0

Instalar

Elige tu cliente

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

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

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

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

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

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": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neon",
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

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

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon

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

Casos de uso

Usos del mundo real: Neon

Prueba una migración Postgres destructiva en una rama de copia en escritura

👤 Ingenieros que ejecutan cambios de esquema en una BD con datos reales ⏱ ~20 min intermediate

Cuándo usarlo: Tienes una migración (DROP COLUMN, UPDATE grande, reconstrucción de índice) y quieres ejecutarla en datos con forma de producción sin arriesgar producción.

Requisitos previos

Clave API de Neon — console.neon.tech → Account → API keys

Flujo

Crea una rama desde main

En el proyecto Neon <id>, crea una rama llamada 'test-drop-legacy' desde la rama main. Devuelve la cadena de conexión de la nueva rama.✓ Copiado

→ Rama creada en <2 segundos, cadena de conexión devuelta
Aplica la migración en la rama

Conéctate a la nueva rama y ejecuta: <pega SQL de migración>. Reporta recuentos de filas y errores.✓ Copiado

→ La migración se completa; los recuentos tienen sentido
Verifica y luego limpia

Ejecuta consultas de verificación en las tablas modificadas. Si los resultados se ven correctos, avísame y aplicaré a main. Luego elimina la rama de todas formas.✓ Copiado

→ Verificación + rama eliminada para evitar cargos de almacenamiento

Resultado: Confianza de que tu migración funciona en datos reales, con cero riesgo para producción.

Errores comunes

La rama consume almacenamiento proporcional a cuánto escribas en ella — Elimina ramas rápidamente después de probar — las ramas abandonadas con escrituras pesadas aumentan la factura
La rama es una instantánea — no ve escrituras que ocurran en main después de la creación de la rama — Crea la rama cerca del momento de aplicación; o usa viaje en el tiempo de Neon para crear una rama desde una marca de tiempo específica

Combinar con: github · postgres

Levanta una base de datos efímera por PR para pruebas de integración

👤 Equipos que ejecutan pruebas de integración CI contra Postgres real ⏱ ~15 min intermediate

Cuándo usarlo: Cada PR necesita su propia BD aislada; los mocks de SQLite no son suficientes.

Flujo

Crea una rama nombrada según el PR

Crea una rama Neon en el proyecto <id> llamada 'pr-482' desde main. Devuelve la cadena de conexión.✓ Copiado

→ Rama lista, cadena de conexión devuelta
Ejecuta el conjunto de pruebas contra ella

Establece DATABASE_URL en esa cadena de conexión. Ejecuta npm run test:integration e informa los resultados.✓ Copiado

→ Las pruebas se ejecutan, resumen de aprobación/fallo
Derribe

Elimina la rama 'pr-482'.✓ Copiado

→ Rama eliminada

Resultado: Pruebas de integración con BD real con aislamiento en segundos, sin contaminación de estado compartido.

Errores comunes

Límites de ramas por proyecto en planes inferiores — Los límites de nivel gratuito importan; ya sea actualiza o implementa un barridor de ramas máx-N

Combinar con: github

Dale a Claude acceso seguro de solo lectura a una BD Neon de producción

👤 Ingenieros depurando datos de producción sin dar al modelo poder de escritura ⏱ ~10 min beginner

Cuándo usarlo: Quieres investigar un problema de producción pero te preocupa una UPDATE fallida.

Flujo

Crea un rol de solo lectura

En el proyecto Neon <id>, crea un rol 'claude_readonly' con acceso solo SELECT en el esquema public. Devuelve su cadena de conexión.✓ Copiado

→ Rol creado; cadena de conexión devuelta
Conecta a través de Postgres MCP

Usa esa cadena de conexión con Postgres MCP. Confirma que puedo ejecutar SELECT pero no INSERT.✓ Copiado

→ SELECT funciona, INSERT da error con 'permiso denegado'
Investiga el problema

Ahora consulta la tabla orders para el user_id afectado 99214. ¿Cuál es el estado de la fila y hay algo inusual?✓ Copiado

→ Diagnóstico concreto de datos reales

Resultado: Una sesión productiva de depuración de producción con seguridad de solo lectura comprobable.

Errores comunes

Olvidando determinar el alcance de tablas futuras — las tablas nuevas no se cubren — Usa ALTER DEFAULT PRIVILEGES para asegurar que las tablas nuevas ceda SELECT a claude_readonly automáticamente

Combinar con: postgres

Revisa la evolución del esquema entre ramas antes de fusionar

👤 DBAs e ingenieros de plataforma ⏱ ~25 min advanced

Cuándo usarlo: Múltiples ramas de características tienen cada una sus propios cambios de esquema; quieres ver el diff acumulativo.

Flujo

Lista las ramas y sus estados

Lista todas las ramas Neon para el proyecto <id>. Para cada una, dame una descripción de una línea de cómo su esquema difiere de main.✓ Copiado

→ Resumen de delta de esquema por rama
Compara dos ramas en detalle

Para la rama 'feature-payments' vs main: compara las tablas, columnas, índices y restricciones. Formatea como una migración SQL.✓ Copiado

→ Diff SQL revisable
Identifica conflictos

Si se fusionan tanto feature-payments como feature-auth, ¿entran en conflicto sus cambios de esquema? ¿Dónde?✓ Copiado

→ Lista de conflictos específica, no 'sin problemas obvios'

Resultado: Orden de fusión más conflictos conocidos antes de que lleguen a main.

Errores comunes

El diff pierde cambios dentro de vistas materializadas o procedimientos almacenados — Sé explícito — pídele a Claude que también compare pg_proc y definiciones de vistas, no solo tablas

Combinar con: github

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

neon + github

BD efímera por PR para pruebas CI, con comentarios de PR mostrando información de conexión

Cuando se abre PR #482, crea una rama Neon 'pr-482', ejecuta migraciones + semillas en ella, publica la cadena de conexión como comentario privado en el PR.✓ Copiado

neon + postgres

Usa Postgres MCP para consultas más seguras de solo lectura una vez que Neon inicia la rama

Crea una rama Neon con rol de solo lectura 'claude_ro'. Luego usa Postgres MCP con esa cadena de conexión para investigar el problema del usuario-99214.✓ Copiado

neon + filesystem

Aplica archivos de migración SQL locales a una rama Neon en orden

Lee cada archivo .sql bajo /db/migrations/ en orden de nombre. Aplícalos en secuencia a la rama Neon 'staging'.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_projects	(ninguno)	Ve tus proyectos Neon	gratis
describe_project	project_id	Obtén una descripción general de un proyecto	gratis
create_branch	project_id, name?, parent_id?, parent_lsn? o parent_timestamp?	Bifurca una rama para pruebas o BDs por PR	almacenamiento de rama facturado por escrituras
list_branches	project_id	Inventaría ramas	gratis
delete_branch	project_id, branch_id	Limpia después de probar — importante para controlar el costo de almacenamiento	gratis
get_connection_string	project_id, branch_id?, role_name?, database_name?	Obtén una cadena de conexión limitada a una rama/rol/bd	gratis
run_sql	project_id, branch_id?, sql: str	Ejecuta SQL contra cualquier rama	tiempo de cómputo facturado
describe_table_schema	project_id, branch_id?, table_name	Inspecciona una tabla sin escribir el SQL tú mismo	gratis
create_role / drop_role	project_id, role_name	Gestiona roles para acceso limitado	gratis
create_database / list_databases	project_id, name	Configuraciones de BD múltiples por proyecto	gratis

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Límites estándar de API Neon por plan
Tokens por llamada: La mayoría de operaciones son pequeñas; los resultados SQL se escalan con el recuento de filas — siempre LIMIT consultas exploratorias
Monetario: MCP gratis; nivel Neon Free cubre proyectos pequeños, planes pagos facturan horas de cómputo y almacenamiento
Consejo: Las ramas son casi gratuitas hasta que acumulan escrituras. La sorpresa de costo #1 son las ramas olvidadas — establece una política de barrido o siempre elimina después de usar.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: limita la clave API a un solo proyecto cuando sea posible

Almacenamiento de credenciales: Clave API en variable de entorno NEON_API_KEY

Salida de datos: Llamadas a la API console.neon.tech; tráfico SQL a tu endpoint regional del proyecto

No conceder nunca: claves de administrador en toda la organización para agentes de larga duración

run_sql puede mutar. Para la rama main de producción, prefiere crear un rol de solo lectura y conectarte a través de Postgres MCP en su lugar.
Las ramas heredan datos del padre en el momento de la creación — contienen cualquier PII que contenga el padre. Trátalas como sensibles.

Resolución de problemas

Errores comunes y soluciones

401 Unauthorized

Clave API inválida o revocada. Genera una nueva en console.neon.tech → Account → API keys.

Verificar: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects

La creación de rama falla: 'límite alcanzado'

Has alcanzado el límite de ramas de tu plan. Elimina ramas sin usar o actualiza.

run_sql agota el tiempo en una migración larga

Las sentencias de larga duración pueden exceder el tiempo de espera predeterminado. Usa psql con la cadena de conexión para operaciones muy largas, o divide la migración.

La cadena de conexión funciona una vez y luego falla (cómputo pausado)

El cómputo del nivel Neon Free se suspende automáticamente. La primera conexión lo despierta (inicio en frío ~1s); las conexiones posteriores están bien. No trates la latencia de la primera llamada como un fallo.

Alternativas

Neon vs otros

Alternativa	Cuándo usarla	Contrapartida
Supabase MCP	Quieres auth, funciones edge, almacenamiento además de Postgres	Superficie más pesada; ramificación limitada al plan Pro
Postgres MCP	Solo necesitas acceso SQL de solo lectura y no usas ramificación	Sin gestión de rama/proyecto
AWS RDS via aws MCP	Estás en Postgres administrado por AWS (RDS/Aurora)	Sin ramificación; el aprovisionamiento es más pesado y lento

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills