Neon

oficial

Interactúa con la plataforma Postgres sin servidor de Neon

GitHub

621

¿Qué puedes hacer con Neon MCP?

Crear proyectos y ramas — Solicita crear un nuevo proyecto o rama de Neon, como "crea una base de datos Postgres llamada my-database", mediante create_project y create_branch.
Ejecutar consultas SQL y transacciones — Ejecuta SQL de una o múltiples declaraciones contra una base de datos usando run_sql o run_sql_transaction, incluyendo escrituras cuando no esté en modo de solo lectura.
Inspeccionar esquemas y tablas — Lista tablas con get_database_tables o extrae la definición completa de columnas/restricciones de una tabla mediante describe_table_schema.
Planificar y aplicar migraciones de forma segura — Inicia una migración con prepare_database_migration para probarla en una rama temporal, luego finalízala con complete_database_migration.
Optimizar consultas lentas — Identifica cuellos de botella con list_slow_queries u obtén planes de ejecución mediante explain_sql_statement, luego prueba correcciones con prepare_query_tuning.
Explorar proyectos y registros — Busca entre organizaciones, proyectos y ramas con search, o filtra registros estructurados usando query_logs y list_log_fields.

Documentación

Servidor MCP de Neon

El servidor MCP de Neon es una herramienta de código abierto que te permite interactuar con tus bases de datos Lakebase Postgres en Neon en lenguaje natural.

El Protocolo de Contexto de Modelos (MCP) es un protocolo estandarizado diseñado para gestionar el contexto entre modelos de lenguaje grandes (LLM) y sistemas externos. Este repositorio proporciona un servidor MCP remoto para Neon.

El servidor MCP de Neon actúa como un puente entre las solicitudes en lenguaje natural y la API de Neon. Construido sobre MCP, traduce tus solicitudes en las llamadas API necesarias, permitiéndote gestionar tareas como crear proyectos y ramas, ejecutar consultas y realizar migraciones de bases de datos sin problemas.

Algunas de las características clave del servidor MCP de Neon incluyen:

Interacción en lenguaje natural: Gestiona bases de datos de Neon mediante comandos conversacionales intuitivos.
Gestión simplificada de bases de datos: Realiza acciones complejas sin escribir SQL ni usar directamente la API de Neon.
Accesibilidad para no desarrolladores: Permite que usuarios con distintos niveles técnicos interactúen con las bases de datos de Neon.
Soporte para migraciones de bases de datos: Aprovecha las capacidades de ramificación de Neon para cambios de esquema de bases de datos iniciados mediante lenguaje natural.

Por ejemplo, en Claude Code, o en cualquier cliente MCP, puedes usar lenguaje natural para realizar tareas con Neon, como:

Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Consideraciones de seguridad del servidor MCP de Neon
El servidor MCP de Neon otorga potentes capacidades de gestión de bases de datos a través de solicitudes en lenguaje natural. Siempre revisa y autoriza las acciones solicitadas por el LLM antes de ejecutarlas. Asegúrate de que solo usuarios y aplicaciones autorizados tengan acceso al servidor MCP de Neon.

El servidor MCP de Neon está diseñado únicamente para desarrollo local e integraciones con IDE. No recomendamos usar el servidor MCP de Neon en entornos de producción. Puede ejecutar operaciones potentes que podrían provocar cambios accidentales o no autorizados.

Para obtener más información, consulta Guía de seguridad de MCP →.

Configuración del servidor MCP de Neon

Hay varias opciones para configurar el servidor MCP de Neon:

Configuración rápida con clave API (Cursor, VS Code y Claude Code): Ejecuta neon@latest init para configurar automáticamente el servidor MCP de Neon, las habilidades de agente y la extensión de VS Code con un solo comando.
Servidor MCP remoto (autenticación basada en OAuth): Conéctate al servidor MCP gestionado de Neon usando OAuth para la autenticación. Este método es más conveniente porque elimina la necesidad de gestionar claves API. Además, recibirás automáticamente las últimas funciones y mejoras en cuanto se publiquen.
Servidor MCP remoto (autenticación basada en clave API): Conéctate al servidor MCP gestionado de Neon usando una clave API para la autenticación. Este método es útil si quieres conectar un agente remoto a Neon donde OAuth no esté disponible. Además, recibirás automáticamente las últimas funciones y mejoras en cuanto se publiquen.

Requisitos previos

Una aplicación cliente MCP.
Una cuenta de Neon.
Node.js (>= v18.0.0): Descárgalo desde nodejs.org.
Si IP Allow está habilitado, añade 34.192.103.46 y 23.22.233.166 a tu lista de permitidos (mcp.neon.tech IPs estáticas).

Para desarrollo, necesitarás Node.js 22+ (pnpm se proporciona a través de Corepack — ejecuta corepack enable para activarlo).

Opción 1. Configuración rápida con clave API

¿No quieres crear una clave API manualmente?

Ejecuta neon@latest init para configurar automáticamente el servidor MCP de Neon con un solo comando:

npx neon@latest init

Esto funciona con Cursor, VS Code (GitHub Copilot) y Claude Code. Autenticará mediante OAuth, creará una clave API de Neon para ti y configurará tu editor automáticamente.

Opción 2. Servidor MCP remoto alojado (autenticación basada en OAuth)

Conéctate al servidor MCP gestionado de Neon usando OAuth para la autenticación. Esta es la configuración más sencilla, no requiere instalación local de este servidor y no necesita una clave API de Neon configurada en el cliente.

Ejecuta el siguiente comando para añadir el servidor MCP de Neon para todos los agentes y editores detectados en tu espacio de trabajo:

npx add-mcp https://mcp.neon.tech/mcp

Añade la bandera -g para agregar el servidor MCP de Neon a la lista global de servidores MCP en lugar del ámbito del proyecto.

Alternativamente, puedes añadir la siguiente entrada "Neon" al archivo de configuración del servidor MCP de tu cliente (p. ej., mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Añade lo siguiente a tu archivo de configuración MCP de Kiro (~/.kiro/settings/mcp.json para global, o .kiro/settings/mcp.json para ámbito de proyecto):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

O usa el botón de instalación de un clic en la parte superior de este README. Para obtener más información, consulta la documentación de MCP de Kiro.

Reinicia o actualiza tu cliente MCP.
Se abrirá una ventana de OAuth en tu navegador. Sigue las instrucciones para autorizar a tu cliente MCP a acceder a tu cuenta de Neon.

Con la autenticación basada en OAuth, el servidor MCP operará, por defecto, en proyectos de tu cuenta personal de Neon. Para acceder o gestionar proyectos que pertenezcan a una organización, debes proporcionar explícitamente org_id o project_id en tu solicitud al cliente MCP.

Opción 3. Servidor MCP remoto alojado (autenticación basada en clave API)

El servidor MCP remoto también admite autenticación mediante una clave API en el encabezado Authorization si tu cliente lo admite.

Crea una clave API de Neon en la consola de Neon. A continuación, ejecuta el siguiente comando para añadir el servidor MCP de Neon para todos los agentes y editores detectados en tu espacio de trabajo:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

Alternativamente, puedes añadir la siguiente entrada "Neon" al archivo de configuración del servidor MCP de tu cliente (p. ej., mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Proporciona una clave API de una organización para limitar el acceso únicamente a los proyectos de esa organización.

Ámbitos y modo de solo lectura

Neon MCP admite los ámbitos de OAuth read, write y * (* significa ambos). Tu cliente MCP puede solicitar estos ámbitos directamente, o puedes hacer la selección en la interfaz de permisos de OAuth.

El modo de solo lectura restringe qué herramientas están disponibles, deshabilitando operaciones de escritura como crear proyectos, ramas o ejecutar migraciones. Las herramientas de solo lectura incluyen listar proyectos, describir esquemas, consultar datos y ver métricas de rendimiento.

Puedes configurar el modo de solo lectura de dos maneras:

Selección de ámbito de OAuth (recomendado): En OAuth, selecciona solo lectura desmarcando Acceso completo en la interfaz de autorización.
Parámetro de consulta readonly: Añade ?readonly=true a la URL de tu servidor MCP:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

Cómo se comporta el parámetro de consulta:

Flujo de clave API: readonly=true es la forma de habilitar el modo de solo lectura (no hay intercambio de ámbitos de OAuth en este flujo).
Flujo de OAuth: readonly=true anula el ámbito de OAuth. Sin él, el modo de solo lectura se determina por el ámbito seleccionado en la interfaz de consentimiento de OAuth.

El encabezado HTTP heredado x-read-only también se admite como respaldo (con menor prioridad que el parámetro de consulta).

Nota: El modo de solo lectura restringe qué herramientas están disponibles. Además, la herramienta run_sql permanece disponible solo para consultas de solo lectura.

Parámetros de consulta de URL para control de acceso

El contexto de concesión (categorías de ámbito, ámbito de proyecto, modo de solo lectura) se configura mediante parámetros de consulta de URL en la URL del servidor MCP. La configuración viaja con cada solicitud y surte efecto de inmediato — sin necesidad de reautenticación.

Parámetro	Descripción	Ejemplo
`readonly`	Habilita el modo de solo lectura (`true`/`false`)	`?readonly=true`
`category`	Restringe a categorías de herramientas específicas (repetido o CSV)	`?category=querying&category=schema`
`projectId`	Limita todas las operaciones a un solo proyecto	`?projectId=proj-123`

Ejemplo de solo lectura + ámbito de proyecto:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

Ejemplo filtrado por categoría (solo herramientas de consulta y esquema):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

Puedes previsualizar qué herramientas son visibles para cualquier configuración usando el endpoint /api/list-tools (sin autenticación requerida):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

Herramientas disponibles en modo de solo lectura

list_projects, list_shared_projects, describe_project, list_organizations
describe_branch, list_branch_computes, compare_database_schema
run_sql, run_sql_transaction, get_database_tables, describe_table_schema
list_slow_queries, explain_sql_statement
get_connection_string
get_neon_auth_config
query_logs, list_log_fields, list_log_field_values
search, fetch, list_docs_resources, get_doc_resource

Herramientas que requieren acceso de escritura:

create_project, delete_project
create_branch, delete_branch, reset_from_parent
provision_neon_auth, configure_neon_auth, provision_neon_data_api
prepare_database_migration, complete_database_migration
prepare_query_tuning, complete_query_tuning

Transporte Server-Sent Events (SSE) (obsoleto)

MCP admite dos transportes de servidor remoto: el obsoleto Server-Sent Events (SSE) y el más reciente y recomendado Streamable HTTP. Si tu cliente LLM aún no admite Streamable HTTP, puedes cambiar el endpoint de https://mcp.neon.tech/mcp a https://mcp.neon.tech/sse para usar SSE.

Ejecuta el siguiente comando para añadir el servidor MCP de Neon para todos los agentes y editores detectados en tu espacio de trabajo usando el transporte SSE:

npx add-mcp https://mcp.neon.tech/sse --type sse

Arquitectura del servidor remoto

El servidor remoto se ejecuta como una aplicación Next.js App Router en Vercel en mcp.neon.tech.

[!NOTE] La ruta raíz / redirige a la documentación del servidor MCP de Neon. No hay página de inicio.

Áreas principales de implementación:

app/api/[transport]/route.ts: endpoint de transporte MCP para Streamable HTTP (/mcp) y SSE (/sse)
app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: endpoints del flujo de OAuth
app/.well-known/: endpoints de metadatos de descubrimiento de OAuth
mcp/: servidor MCP, herramientas, manejadores, analíticas e integración con Sentry
lib/: ayudantes compatibles con Next.js (OAuth, configuración, manejo de errores)
mcp/utils/read-only.ts: manejo del modo de solo lectura y ámbitos

Guías

Funciones

Herramientas admitidas

El servidor MCP de Neon proporciona las siguientes acciones, que se exponen como "herramientas" a los clientes MCP. Puedes usar estas herramientas para interactuar con tus proyectos y bases de datos de Neon mediante comandos en lenguaje natural.

Metadatos de ámbito de herramientas

Cada definición de herramienta incluye una categoría scope utilizada para el filtrado de herramientas basado en concesiones y la experiencia de consentimiento. Las categorías actuales son:

projects
branches
schema
querying
neon_auth
data_api
observability
docs
null (herramientas sin categoría de ámbito)

Notas:

compare_database_schema está categorizado bajo schema.
provision_neon_data_api está categorizado bajo data_api (separado de neon_auth).
La aplicación de solo lectura sigue dependiendo de readOnlySafe y de la lógica de solo lectura del servidor; scope es metadatos de categoría, no un interruptor independiente de lectura/escritura.
En el modo de ámbito de proyecto (?projectId=...), search y fetch no están disponibles.

Gestión de proyectos:

list_projects: Lista los primeros 10 proyectos de Neon en tu cuenta, proporcionando un resumen de cada proyecto. Si no puedes encontrar un proyecto específico, aumenta el límite pasando un valor mayor al parámetro limit.
list_shared_projects: Lista los proyectos de Neon compartidos con el usuario actual. Admite un parámetro de búsqueda y limita el número de proyectos devueltos (predeterminado: 10).
describe_project: Obtiene información detallada sobre un proyecto específico de Neon, incluidos su ID, nombre y las ramas y bases de datos asociadas.
create_project: Crea un nuevo proyecto de Neon en tu cuenta. Un proyecto actúa como contenedor de ramas, bases de datos, roles y computación.
delete_project: Elimina un proyecto existente de Neon y todos sus recursos asociados.
list_organizations: Lista todas las organizaciones a las que el usuario actual tiene acceso. Opcionalmente, filtra por nombre o ID de organización usando el parámetro de búsqueda.

Gestión de ramas:

create_branch: Crea una nueva rama dentro de un proyecto de Neon especificado. Aprovecha la función de ramificación de Neon para desarrollo, pruebas o migraciones.
delete_branch: Elimina una rama existente de un proyecto de Neon.
describe_branch: Recupera detalles sobre una rama específica, como su nombre, ID y rama principal.
list_branch_computes: Lista los endpoints de cómputo de un proyecto o rama específica, incluidos ID de cómputo, tipo, tamaño, última actividad e información de autoescalado.
compare_database_schema: Muestra la diferencia de esquema entre la rama hija y su rama principal.
reset_from_parent: Restablece la rama actual al estado de su rama principal, descartando los cambios locales. Conserva automáticamente una copia de seguridad si la rama tiene hijos, o conserva opcionalmente bajo petición con un nombre personalizado.

Ejecución de consultas SQL:

get_connection_string: Devuelve tu cadena de conexión a la base de datos.
run_sql: Ejecuta una única consulta SQL contra una base de datos de Neon especificada. Admite operaciones de lectura y escritura.
run_sql_transaction: Ejecuta una serie de consultas SQL dentro de una sola transacción contra una base de datos de Neon.
get_database_tables: Lista todas las tablas dentro de una base de datos de Neon especificada.
describe_table_schema: Recupera la definición de esquema de una tabla específica, detallando columnas, tipos de datos y restricciones.

Migraciones de base de datos (cambios de esquema):

prepare_database_migration: Inicia un proceso de migración de base de datos. De forma crítica, crea una rama temporal para aplicar y probar la migración de forma segura antes de afectar a la rama principal.
complete_database_migration: Finaliza y aplica una migración de base de datos preparada a la rama principal. Esta acción fusiona los cambios de la rama de migración temporal y limpia los recursos temporales.

Consultas y optimización SQL:

list_slow_queries: Identifica cuellos de botella de rendimiento encontrando las consultas más lentas de una base de datos. Requiere la extensión pg_stat_statements.
explain_sql_statement: Proporciona planes de ejecución detallados para consultas SQL para ayudar a identificar cuellos de botella de rendimiento.
prepare_query_tuning: Analiza el rendimiento de las consultas y sugiere optimizaciones, como la creación de índices. Crea una rama temporal para probar estas optimizaciones de forma segura.
complete_query_tuning: Finaliza el ajuste de consultas aplicando las optimizaciones a la rama principal o descartándolas. Limpia la rama temporal de ajuste.

Neon Auth:

provision_neon_auth: Aprovisiona Neon Auth para un proyecto de Neon. Permite a los desarrolladores configurar fácilmente la infraestructura de autenticación creando una integración con un proveedor de autenticación.
configure_neon_auth: Configura una integración existente de Neon Auth para una rama: gestiona orígenes de confianza, acceso de localhost, métodos de autenticación, proveedores OAuth y el proveedor de correo electrónico transaccional.
get_neon_auth_config: Lee la configuración completa de Neon Auth para una rama, incluidos los metadatos de integración y los ajustes configurables (los secretos están redactados).

Neon Data API:

provision_neon_data_api: Aprovisiona la Neon Data API para acceso a la base de datos basado en HTTP con autenticación JWT opcional mediante Neon Auth o proveedores JWKS externos.

Búsqueda y descubrimiento:

search: Busca en organizaciones, proyectos y ramas que coincidan con una consulta. Devuelve IDs, títulos y enlaces directos a la consola de Neon.
fetch: Obtiene información detallada sobre una organización, proyecto o rama específicos usando un ID (normalmente de la herramienta de búsqueda).

Observabilidad:

query_logs: Consulta los registros emitidos por tus funciones serverless de Neon y otros servicios usando filtros estructurados (fuente, nombre del servicio, severidad, ventana de tiempo). Los registros están basados en OpenTelemetry.
list_log_fields: Lista los campos de registro (etiquetas) sobre los que puedes filtrar para una rama, como service_name, severity_text y scope_name. Usa antes de query_logs.
list_log_field_values: Lista los valores distintos de un campo de registro dentro de una rama y ventana de tiempo, para descubrir valores concretos que pasar a query_logs.

Documentación y recursos:

list_docs_resources: Lista todas las páginas de documentación de Neon disponibles obteniendo el índice de https://neon.com/docs/llms.txt. Devuelve URLs y títulos de páginas que se pueden obtener individualmente usando la herramienta get_doc_resource.
get_doc_resource: Obtiene una página específica de documentación de Neon como contenido Markdown. Usa primero la herramienta list_docs_resources para descubrir los slugs de página disponibles y luego pasa el slug a esta herramienta.

Migraciones

Las migraciones son una forma de gestionar los cambios en el esquema de tu base de datos a lo largo del tiempo. Con el servidor MCP de Neon, los LLM pueden realizar migraciones de forma segura con comandos separados de "Inicio" (prepare_database_migration) y "Confirmación" (complete_database_migration).

El comando "Inicio" acepta una migración y la ejecuta en una nueva rama temporal. Al regresar, este comando sugiere al LLM que debe probar la migración en esta rama. El LLM puede entonces ejecutar el comando "Confirmación" para aplicar la migración a la rama original.

Desarrollo

Este proyecto usa pnpm como gestor de paquetes, fijado mediante Corepack.

Estructura del proyecto

El código del servidor MCP se encuentra en la raíz del repositorio, una aplicación Next.js desplegada en Vercel en mcp.neon.tech.

corepack enable
pnpm install

Desarrollo local

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

Linting y comprobación de tipos

pnpm lint
pnpm typecheck

Variables de entorno

Requeridas para el entorno de ejecución del servidor remoto:

Variable	Descripción
`SERVER_HOST`	URL del servidor (predeterminado: `VERCEL_URL`)
`UPSTREAM_OAUTH_HOST`	URL del proveedor OAuth de Neon
`CLIENT_ID`	ID de cliente OAuth
`CLIENT_SECRET`	Secreto de cliente OAuth
`COOKIE_SECRET`	Secreto para cookies firmadas
`KV_URL`	URL de Vercel KV (Upstash Redis)
`OAUTH_DATABASE_URL`	URL de Postgres para almacenamiento de tokens

Opcionales:

Variable	Descripción
`LOG_LEVEL`	Nivel de registro de Winston: `error`, `warn`, `info` (predeterminado), `debug`, `verbose`, `silly`

Pirámide de pruebas

Todas las pruebas se ejecutan desde la raíz del repositorio.

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

Estrategia de pruebas:

Prefiere pruebas E2E para el transporte/protocolo y el comportamiento visible para el usuario.
Usa pruebas de integración para contratos de herramientas deterministas y comportamiento de flujos de trabajo.
Usa pruebas unitarias para lógica pura y casos límite.
Evita depender de la disponibilidad de terceros en pruebas que bloquean fusiones; simula dependencias externas en los niveles de integración/unitarias.

Despliegue

Vercel despliega el servidor remoto automáticamente desde la configuración de ramas del repositorio. Los entornos de vista previa están disponibles para las solicitudes de extracción.