Neon MCP Server

oficial

Interact with the Neon serverless Postgres platform

Documentación

Servidor MCP de Neon

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

El Protocolo de Contexto de Modelo (MCP) es un protocolo estandarizado diseñado para gestionar el contexto entre modelos de lenguaje de gran tamaño (LLMs) 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 Neon usando comandos intuitivos y conversacionales.
Gestión de bases de datos simplificada: Realiza acciones complejas sin escribir SQL ni usar directamente la API de Neon.
Accesibilidad para no desarrolladores: Permite a usuarios con distintos conocimientos técnicos interactuar con bases de datos Neon.
Soporte para migraciones de bases de datos: Aprovecha las capacidades de ramificación de Neon para cambios en el esquema de la base de datos iniciados mediante lenguaje natural.

Por ejemplo, en Claude Code, o cualquier Cliente MCP, puedes usar lenguaje natural para lograr cosas 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 su ejecución. Asegúrate de que solo usuarios y aplicaciones autorizados tengan acceso al servidor MCP de Neon.

El servidor MCP de Neon está destinado únicamente para desarrollo local e integraciones en 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 más información, consulta la guía de seguridad de MCP →.

Configuración del servidor MCP de Neon

Existen varias opciones para configurar el servidor MCP de Neon:

Configuración rápida con clave API (Cursor, VS Code y Claude Code): Ejecuta neonctl@latest init para configurar automáticamente el servidor MCP de Neon, las habilidades del 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 ya que elimina la necesidad de gestionar claves API. Además, recibirás automáticamente las últimas funciones y mejoras tan pronto como 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 deseas conectar un agente remoto a Neon donde OAuth no está disponible. Además, recibirás automáticamente las últimas funciones y mejoras tan pronto como se publiquen.

Requisitos previos

Una aplicación Cliente MCP.
Una cuenta de Neon.
Node.js (>= v18.0.0): Descárgalo desde nodejs.org.

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 manualmente una clave API?

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

npx neonctl@latest init

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

Opción 2. Servidor MCP alojado remoto (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 agregar 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

Agrega la bandera -g para añadir el servidor MCP de Neon a la lista global de servidores MCP en lugar de al ámbito del proyecto.

Alternativamente, puedes agregar la siguiente entrada "Neon" al archivo de configuración del servidor MCP de tu cliente (por ejemplo, mcp.json, mcp_config.json):

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

Kiro: Agrega 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 con un clic en la parte superior de este README. Para más información, consulta la documentación de Kiro MCP.

Reinicia o actualiza tu cliente MCP.
Se abrirá una ventana de OAuth en tu navegador. Sigue las indicaciones 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 bajo tu cuenta personal de Neon. Para acceder o gestionar proyectos que pertenecen a una organización, debes proporcionar explícitamente org_id o project_id en tu solicitud al cliente MCP.

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

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

Crea una clave API de Neon en la Consola de Neon. Luego, ejecuta el siguiente comando para agregar 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 agregar la siguiente entrada "Neon" al archivo de configuración del servidor MCP de tu cliente (por ejemplo, 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 solo a los proyectos bajo esa organización.

Ámbitos y modo de solo lectura

Neon MCP admite los ámbitos 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 OAuth (recomendado): En OAuth, selecciona solo lectura desmarcando Acceso completo en la interfaz de autorización.
Parámetro de consulta readonly: Agrega ?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 ámbito OAuth en este flujo).
Flujo OAuth: readonly=true anula el ámbito OAuth. Sin él, el modo de solo lectura se determina por el ámbito seleccionado en la interfaz de consentimiento OAuth.

El encabezado HTTP heredado x-read-only también es compatible como respaldo (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 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 URL en la URL del servidor MCP. La configuración viaja con cada solicitud y tiene efecto inmediato — no es necesario volver a autenticarse.

Parámetro	Descripción	Ejemplo
`readonly`	Habilitar modo de solo lectura (`true`/`false`)	`?readonly=true`
`category`	Restringir a categorías de herramientas específicas (repetido o CSV)	`?category=querying&category=schema`
`projectId`	Limitar 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 de 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 (no requiere autenticación):

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
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, provision_neon_data_api
prepare_database_migration, complete_database_migration
prepare_query_tuning, complete_query_tuning

Transporte de Eventos Enviados por el Servidor (SSE) (Obsoleto)

MCP admite dos transportes de servidor remoto: el obsoleto Eventos Enviados por el Servidor (SSE) y el más nuevo y recomendado HTTP Transmisible. Si tu cliente LLM aún no admite HTTP Transmisible, puedes cambiar el endpoint de https://mcp.neon.tech/mcp a https://mcp.neon.tech/sse para usar SSE en su lugar.

Ejecuta el siguiente comando para agregar 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:

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

Guías

Características

Herramientas compatibles

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 Neon usando 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
docs
null (herramientas sin una 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 del modo de solo lectura aún depende de readOnlySafe y la lógica de solo lectura del lado del servidor; scope es metadato de categoría, no un interruptor independiente de lectura/escritura.
En modo de ámbito de proyecto (?projectId=...), search y fetch no están disponibles.

Gestión de proyectos:

list_projects: Enumera los primeros 10 proyectos Neon de tu cuenta, proporcionando un resumen de cada uno. Si no encuentras un proyecto específico, aumenta el límite pasando un valor más alto al parámetro limit.
list_shared_projects: Enumera los proyectos 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 Neon específico, incluyendo su ID, nombre y las ramas y bases de datos asociadas.
create_project: Crea un nuevo proyecto Neon en tu cuenta de Neon. Un proyecto actúa como contenedor para ramas, bases de datos, roles y computes.
delete_project: Elimina un proyecto Neon existente y todos sus recursos asociados.
list_organizations: Enumera 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 Neon especificado. Aprovecha la funcionalidad de ramificación de Neon para desarrollo, pruebas o migraciones.
delete_branch: Elimina una rama existente de un proyecto Neon.
describe_branch: Recupera detalles sobre una rama específica, como su nombre, ID y rama padre.
list_branch_computes: Enumera los endpoints de cómputo para un proyecto o rama específica, incluyendo ID de cómputo, tipo, tamaño, última hora de actividad e información de autoescalado.
compare_database_schema: Muestra la diferencia de esquema entre la rama hija y su padre.
reset_from_parent: Restablece la rama actual al estado de su padre, descartando los cambios locales. Preserva automáticamente en una copia de seguridad si la rama tiene hijos, u opcionalmente preserva 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 Neon especificada. Admite operaciones de lectura y escritura.
run_sql_transaction: Ejecuta una serie de consultas SQL dentro de una única transacción contra una base de datos Neon.
get_database_tables: Enumera todas las tablas dentro de una base de datos Neon especificada.
describe_table_schema: Recupera la definición del 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 manera 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 SQL y Optimización:

list_slow_queries: Identifica cuellos de botella de rendimiento encontrando las consultas más lentas en 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 de ajuste temporal.

Neon Auth:

provision_neon_auth: Aprovisiona Neon Auth para un proyecto Neon. Permite a los desarrolladores configurar fácilmente la infraestructura de autenticación creando una integración con un proveedor de Auth.

API de Datos de Neon:

provision_neon_data_api: Aprovisiona la API de Datos de Neon para acceso a bases de datos basado en HTTP con autenticación JWT opcional a través de 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ífica usando un ID (normalmente de la herramienta de búsqueda).

Documentación y Recursos:

list_docs_resources: Enumera todas las páginas de documentación de Neon disponibles obteniendo el índice de https://neon.com/docs/llms.txt. Devuelve URLs de páginas y títulos 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, 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 LLMs están capacitados para 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 indica 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 reside en el directorio landing/, que es una aplicación Next.js desplegada en Vercel en mcp.neon.tech.

cd landing
corepack enable
pnpm install

Desarrollo Local

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

Linting y Comprobación de Tipos

pnpm run lint
pnpm run typecheck

Variables de Entorno

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

Variable	Descripción
`SERVER_HOST`	URL del servidor (por defecto `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 landing/.

cd landing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

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

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

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

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

Estrategia de pruebas:

Preferir E2E para transporte/protocolo y comportamiento visible para el usuario.
Usar pruebas de integración para contratos de herramientas deterministas y comportamiento del flujo de trabajo.
Usar pruebas unitarias para lógica pura y casos límite.
Evitar depender del tiempo de actividad de terceros en pruebas de bloqueo de fusión; simular dependencias externas en los niveles de integración/unidad.

Despliegue

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