Neon

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

Neon MCP Server

Neon MCP Server ist ein Open-Source-Tool, mit dem Sie in natürlicher Sprache mit Ihren Lakebase-Postgres-Datenbanken auf Neon interagieren können.

Das Model Context Protocol (MCP) ist ein standardisiertes Protokoll, das dafür entwickelt wurde, den Kontext zwischen großen Sprachmodellen (LLMs) und externen Systemen zu verwalten. Dieses Repository stellt einen Remote-MCP-Server für Neon bereit.

Der MCP-Server von Neon fungiert als Brücke zwischen Anfragen in natürlicher Sprache und der Neon API. Er basiert auf MCP und übersetzt Ihre Anfragen in die erforderlichen API-Aufrufe. So können Sie Aufgaben wie das Erstellen von Projekten und Branches, das Ausführen von Abfragen und Datenbankmigrationen nahtlos verwalten.

Zu den wichtigsten Funktionen des Neon MCP-Servers gehören:

• Interaktion in natürlicher Sprache: Verwalten Sie Neon-Datenbanken mit intuitiven, dialogorientierten Befehlen.
• Vereinfachte Datenbankverwaltung: Führen Sie komplexe Aktionen aus, ohne SQL zu schreiben oder die Neon API direkt zu verwenden.
• Zugänglichkeit für Nicht-Entwickler: Ermöglichen Sie Benutzern mit unterschiedlichem technischem Hintergrund die Interaktion mit Neon-Datenbanken.
• Unterstützung für Datenbankmigrationen: Nutzen Sie die Branching-Funktionen von Neon für Schemaänderungen an Datenbanken, die über natürliche Sprache angestoßen werden.

In Claude Code oder einem beliebigen MCP-Client können Sie beispielsweise in natürlicher Sprache Aufgaben mit Neon erledigen, etwa:

• 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]
Sicherheitshinweise zum Neon MCP Server
Der Neon MCP Server ermöglicht über Anfragen in natürlicher Sprache leistungsstarke Funktionen zur Datenbankverwaltung. Überprüfen und autorisieren Sie die vom LLM angeforderten Aktionen immer, bevor sie ausgeführt werden. Stellen Sie sicher, dass nur autorisierte Benutzer und Anwendungen Zugriff auf den Neon MCP Server haben.

Der Neon MCP Server ist ausschließlich für die lokale Entwicklung und IDE-Integrationen vorgesehen. Wir empfehlen nicht, den Neon MCP Server in Produktionsumgebungen einzusetzen. Er kann leistungsstarke Vorgänge ausführen, die zu versehentlichen oder unbefugten Änderungen führen können.

Weitere Informationen finden Sie unter Sicherheitshinweise zu MCP →.

Neon MCP Server einrichten

Es gibt mehrere Möglichkeiten, den Neon MCP Server einzurichten:

1. Schnelleinrichtung mit API-Schlüssel (Cursor, VS Code und Claude Code): Führen Sie neon@latest init aus, um den MCP Server von Neon, Agent-Skills und die VS Code-Erweiterung automatisch mit einem einzigen Befehl zu konfigurieren.
2. Remote-MCP-Server (OAuth-basierte Authentifizierung): Stellen Sie über OAuth eine Verbindung zum verwalteten MCP-Server von Neon her. Diese Methode ist praktischer, da keine API-Schlüssel verwaltet werden müssen. Außerdem erhalten Sie automatisch die neuesten Funktionen und Verbesserungen, sobald sie veröffentlicht werden.
3. Remote-MCP-Server (API-Schlüssel-basierte Authentifizierung): Stellen Sie zur Authentifizierung über einen API-Schlüssel eine Verbindung zum verwalteten MCP-Server von Neon her. Diese Methode ist nützlich, wenn Sie einen Remote-Agenten mit Neon verbinden möchten und OAuth nicht verfügbar ist. Außerdem erhalten Sie automatisch die neuesten Funktionen und Verbesserungen, sobald sie veröffentlicht werden.

Voraussetzungen

• Eine MCP-Client-Anwendung.
• Ein Neon-Konto.
• Node.js (>= v18.0.0): Herunterladen unter nodejs.org.
• Wenn IP Allow aktiviert ist, fügen Sie 34.192.103.46 und 23.22.233.166 zu Ihrer Zulassungsliste hinzu (mcp.neon.tech statische IPs).

Für die Entwicklung benötigen Sie Node.js 22+ (pnpm wird über Corepack bereitgestellt — führen Sie corepack enable aus, um es zu aktivieren).

Option 1. Schnelleinrichtung mit API-Schlüssel

Möchten Sie keinen API-Schlüssel manuell erstellen?

Führen Sie neon@latest init aus, um den MCP Server von Neon automatisch mit einem einzigen Befehl zu konfigurieren:

npx neon@latest init

Dies funktioniert mit Cursor, VS Code (GitHub Copilot) und Claude Code. Die Authentifizierung erfolgt über OAuth, ein Neon-API-Schlüssel wird für Sie erstellt und Ihr Editor wird automatisch konfiguriert.

Option 2. Gehosteter Remote-MCP-Server (OAuth-basierte Authentifizierung)

Stellen Sie zur Authentifizierung über OAuth eine Verbindung zum verwalteten MCP-Server von Neon her. Dies ist die einfachste Einrichtung: Sie erfordert keine lokale Installation dieses Servers und keinen im Client konfigurierten Neon-API-Schlüssel.

Führen Sie den folgenden Befehl aus, um den Neon MCP Server für alle erkannten Agenten und Editoren in Ihrem Arbeitsbereich hinzuzufügen:

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"

Diese URL stellt Projekte, Branches, Compute-Endpunkte, Abfragen und Schemas bereit. Zeigen Sie eine Vorschau mit /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema an. Die ungefilterte URL stellt alle Kategorien bereit:

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

Fügen Sie das Flag -g hinzu, um den Neon MCP Server zur globalen MCP-Serverliste statt zum projektbezogenen Bereich hinzuzufügen.

Alternativ können Sie den folgenden Eintrag „Neon“ zur MCP-Server-Konfigurationsdatei Ihres Clients hinzufügen (z. B. mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
    }
  }
}

Kiro: Fügen Sie Folgendes zu Ihrer Kiro-MCP-Konfigurationsdatei hinzu (~/.kiro/settings/mcp.json für den globalen oder .kiro/settings/mcp.json für den projektbezogenen Bereich):

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

Oder verwenden Sie die Schaltfläche zur Ein-Klick-Installation oben in dieser README. Weitere Informationen finden Sie in der Kiro-MCP-Dokumentation.

• Starten Sie Ihren MCP-Client neu oder aktualisieren Sie ihn.
• In Ihrem Browser wird ein OAuth-Fenster geöffnet. Folgen Sie den Anweisungen, um Ihrem MCP-Client den Zugriff auf Ihr Neon-Konto zu erlauben.

Bei der OAuth-basierten Authentifizierung arbeitet der MCP-Server standardmäßig mit Projekten in Ihrem persönlichen Neon-Konto. Um auf Projekte einer Organisation zuzugreifen oder diese zu verwalten, müssen Sie in Ihrer Eingabe an den MCP-Client ausdrücklich entweder org_id oder project_id angeben.

Option 3. Gehosteter Remote-MCP-Server (API-Schlüssel-basierte Authentifizierung)

Der Remote-MCP-Server unterstützt auch die Authentifizierung mit einem API-Schlüssel im Header Authorization, sofern Ihr Client dies unterstützt.

Erstellen Sie einen Neon-API-Schlüssel in der Neon Console. Führen Sie anschließend den folgenden Befehl aus, um den Neon MCP Server für alle erkannten Agenten und Editoren in Ihrem Arbeitsbereich hinzuzufügen:

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema" --header "Authorization: Bearer <$NEON_API_KEY>"

Alternativ können Sie den folgenden Eintrag „Neon“ zur MCP-Server-Konfigurationsdatei Ihres Clients hinzufügen (z. B. mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Geben Sie den API-Schlüssel einer Organisation an, um den Zugriff auf Projekte innerhalb dieser Organisation zu beschränken.

Bereiche und schreibgeschützter Modus

Neon MCP stellt die OAuth-Bereiche read und write bereit. Ihr MCP-Client kann diese anfordern, oder Sie können sie in der OAuth-Berechtigungsoberfläche auswählen. * wird als Schreibzugriff behandelt, wenn ein Client diesen Wert weiterhin sendet.

Der schreibgeschützte Modus schränkt die verfügbaren Tools ein und deaktiviert Schreibvorgänge wie das Erstellen von Projekten und Branches oder das Ausführen von Migrationen. Zu den schreibgeschützten Tools gehören das Auflisten von Projekten, das Beschreiben von Schemas, das Abfragen von Daten und das Anzeigen von Leistungsmetriken.

Sie können den schreibgeschützten Modus auf zwei Arten festlegen:

1. Standard-MCP-URL (bearbeitbare Zustimmung): Stellen Sie mit https://mcp.neon.tech/mcp eine Verbindung her und deaktivieren Sie auf der Autorisierungsseite Schreibzugriff erlauben. Dort können Sie auch ein Projekt, eine Postgres-Rolle für SQL und eine Teilmenge der Tool-Kategorien auswählen.
2. Parametrisierte MCP-URL (feste Zustimmung): Fügen Sie readonly, projectId, category und/oder roleName zur MCP-Server-URL hinzu. Die Autorisierungsseite bestätigt diese Berechtigung und bietet keine Bearbeitungsmöglichkeiten. Ändern Sie die URL und autorisieren Sie erneut, um die Berechtigung zu ändern.

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

Verhalten des Abfrageparameters:

• API-Schlüssel-Ablauf: readonly=true ist die Möglichkeit, den schreibgeschützten Modus zu aktivieren (in diesem Ablauf findet kein OAuth-Scope-Austausch statt). Änderungen an der URL werden bei der nächsten Anfrage wirksam.
• OAuth-Ablauf: projectId, category, readonly und roleName in der MCP-URL legen eine feste Berechtigung fest, die bei der Autorisierung bestätigt wird. readonly=true kann auf dieser Seite nicht auf Schreibzugriff erweitert werden. Nach der Ausstellung eines Tokens erweitert eine Änderung der URL dessen Berechtigungen nicht; autorisieren Sie erneut.

Bei der OAuth-Registrierung ist x-read-only ein anfänglicher Standardwert für „Schreibzugriff erlauben“ bei bearbeitbarer Zustimmung. Er sperrt die Bestätigung nicht und schränkt keine parametrisierte URL ein, die readonly=false enthält. API-Schlüssel-Anfragen berücksichtigen weiterhin x-read-only pro Anfrage, zusätzlich zum Abfrageparameter readonly.

Hinweis: Der schreibgeschützte Modus schränkt ein, welche Tools verfügbar sind. run_sql bleibt verfügbar und führt jede Abfrage in einer READ ONLY-Transaktion aus. run_sql_transaction ist nicht verfügbar; führen Sie jede Anweisung mit run_sql aus. Diese Aufrufe werden separat ausgeführt und verwenden keine gemeinsame Transaktion. Für Transaktionssemantik verwenden Sie eine Verbindung mit aktiviertem Schreibzugriff.

URL-Abfrageparameter für die Zugriffskontrolle

Der Berechtigungskontext (Scope-Kategorien, Projektbeschränkung, schreibgeschützter Modus, festgelegte Postgres-Rolle) wird über URL-Abfrageparameter in der MCP-Server-URL konfiguriert. API-Schlüssel-Anfragen wenden diese Parameter bei jeder Anfrage an. OAuth-Tokens speichern die bei der Autorisierung bestätigte oder bearbeitete Berechtigung.

Parameter	Beschreibung	Beispiel
readonly	Schreibgeschützten Modus aktivieren (true/false)	?readonly=true
category	Auf bestimmte Tool-Kategorien beschränken (wiederholt oder CSV)	?category=querying&category=schema
projectId	Alle Vorgänge auf ein einzelnes Projekt beschränken	?projectId=proj-123
roleName	Gesamtes SQL mit dieser Postgres-Rolle statt mit dem Eigentümer ausführen	?roleName=app_reader

Beispiel: schreibgeschützt und auf ein Projekt beschränkt:

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

Beispiel mit Kategorienfilter (nur Abfrage- und Schema-Tools):

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

Beispiel mit festgelegter Postgres-Rolle (schreibgeschützt, ein Projekt, SQL als app_reader):

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

roleName legt die Postgres-Anmelderolle für die gesamte Verbindung fest. Jedes SQL, das der Server für Sie ausführt (run_sql, run_sql_transaction, explain_sql_statement, get_database_tables, describe_table_schema, describe_branch, list_slow_queries, inspect_database sowie das SQL innerhalb von Migrationen und Abfrageoptimierungen), wird mit dieser Rolle angemeldet. Dadurch bestimmen die Postgres-Berechtigungen, was der Agent lesen oder ändern kann. Ohne diese Einstellung wird SQL als Datenbankeigentümer ausgeführt. Im schreibgeschützten Modus werden Abfragen weiterhin in einer READ ONLY-Transaktion ausgeführt. Die festgelegte Rolle fügt eine von Postgres direkt bei der Anmeldung durchgesetzte Beschränkung hinzu, sodass SQL, das aus der Transaktion entkommt, weiterhin nur über die Berechtigungen dieser Rolle verfügt.

• Der Server löst die Anmeldedaten der Rolle intern auf und gibt sie niemals zurück. get_connection_string ist bei einer festgelegten Verbindung nicht verfügbar.
• Ein role_name-Toolargument, das von der festgelegten Rolle abweicht, wird abgelehnt. Wird es weggelassen, wird die festgelegte Rolle verwendet, niemals der Eigentümer.
• Wenn die Rolle nicht existiert oder sich nicht anmelden kann (zum Beispiel ALTER ROLE … NOLOGIN), schlägt der Aufruf fehl, bevor SQL ausgeführt wird. Es wird nicht mit einer anderen Rolle erneut versucht.
• Der Wert muss genau einem Postgres-Rollennamen entsprechen: Buchstaben, Ziffern, _ oder $, beginnend mit einem Buchstaben oder _, höchstens 63 Zeichen. Alles andere (leer, wiederholt, in Anführungszeichen gesetzt, mit Bindestrichen) wird mit 400 abgelehnt und nicht ignoriert.
• Die Rolle muss sich anmelden können (LOGIN) und auf jedem abgefragten Branch existieren. Mit SQL erstellte Rollen (CREATE ROLE app_reader LOGIN PASSWORD '…') funktionieren ebenso wie Rollen, die in der Neon Console oder über die API erstellt wurden. Eine Rolle mit den benötigten und keinen weiteren Berechtigungen macht die Festlegung sinnvoll: Gewähre schreibgeschützten Agents SELECT auf den Tabellen, die sie sehen sollen, und füge sie nicht zu neon_superuser hinzu. create_postgres_role mit access: "read_only" erstellt eine solche Rolle über eine Verbindung ohne roleName; Rollen, die ohne access erstellt werden, treten neon_superuser bei.
• OAuth: roleName in der MCP-URL legt eine feste Berechtigung fest. Auf der Autorisierungsseite wird die Rolle angezeigt, und das ausgestellte Token behält sie auch nach der Aktualisierung bei. Eine spätere Änderung der URL ändert das Token nicht; autorisiere erneut. Gib bei der Standard-URL (bearbeitbare Einwilligung) stattdessen die Rolle im optionalen Feld Postgres role ein; lasse es leer, um den Datenbankeigentümer beizubehalten. Vor dieser Option ausgestellte Tokens haben keine festgelegte Rolle und verhalten sich wie bisher.
• API-Schlüssel: Die Rolle wird bei jeder Anfrage aus der URL gelesen. Wer die Verbindungs-URL bearbeiten kann und den API-Schlüssel besitzt, kann sie ändern oder entfernen. Bewahre die URL daher in einer Konfiguration auf, die der Agent nicht kontrolliert.
• Die Festlegung gilt nur für SQL-Verbindungen. Management-API-Tools verwenden weiterhin die eigenen Zugriffsrechte des API-Schlüssels oder OAuth-Tokens; compare_database_schema wird beispielsweise von der Neon API berechnet und nicht durch die Berechtigungen der Rolle eingeschränkt. Kombiniere roleName mit readonly=true und category, um auch diese Tools einzuschränken.

Mit dem Endpunkt /api/list-tools kannst du für jede Konfiguration eine Vorschau der sichtbaren Tools anzeigen (keine Authentifizierung erforderlich):

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

Im schreibgeschützten Modus verfügbare Tools

Benutzerdefinierte Tools: list_organizations, describe_branch, run_sql, get_database_tables, describe_table_schema, list_slow_queries, explain_sql_statement, inspect_database, get_neon_auth_config, search, fetch, search_docs, get_doc, send_feedback, list_incidents.

Generierte Management-API-Tools, die GET verwenden und keine Geheimnisse zurückgeben, sowie query_logs (POST, schreibgeschützt). Mit /api/list-tools?readonly=true kannst du die genaue Auswahl anzeigen.

Tools, die Schreibzugriff erfordern:

• Schreibzugriffe der generierten Management-API (create_project, create_branch, delete_project, …)
• get_connection_string (die Verbindungszeichenfolge enthält das Passwort einer privilegierten Rolle und wird daher im schreibgeschützten Modus zurückgehalten; kopiere sie stattdessen aus der Neon Console)
• run_sql_transaction (die Anweisungen werden in einer Sitzung ausgeführt, daher würde eine COMMIT- oder SET TRANSACTION READ WRITE-Anweisung die schreibgeschützte Transaktion beenden)
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Transportkompatibilität

https://mcp.neon.tech/mcp verwendet zustandsloses Streamable HTTP. Es unterstützt das MCP-Protokoll 2026-07-28 sowie einen zustandslosen Fallback für Clients aus der Ära 2025. Die veralteten HTTP+SSE-Endpunkte /sse und /message geben 410 Gone zurück.

Verbinde Streamable-HTTP-Clients mit https://mcp.neon.tech/mcp. Für Clients, die nur lokale stdio-Server unterstützen, füge dies in die Clientkonfiguration ein, damit mcp-remote eine Verbindung zu Streamable HTTP herstellt:

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.neon.tech/mcp"]
    }
  }
}

Eine Anfrage mit einem fehlerhaften Origin-Header erhält 403 Forbidden. Jede serialisierte Origin wird akzeptiert, einschließlich Webseiten, Browsererweiterungen, Desktop- Webviews und null, sodass browserbasierte Clients eine Verbindung herstellen können. Anfragen ohne Origin sind davon nicht betroffen.

Architektur des Remote-Servers

Der Remote-Server läuft als Next.js-App-Router-Anwendung auf Vercel unter mcp.neon.tech.

[!NOTE] Der Stamm-/-Pfad leitet zu Neon MCP Server docs weiter. Es gibt keine Landingpage.

Zentrale Implementierungsbereiche:

• app/api/[transport]/route.ts: zustandsloser Streamable-HTTP-Endpunkt (/mcp)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: OAuth-Flow-Endpunkte
• app/.well-known/: OAuth-Discovery-Metadaten-Endpunkte
• mcp/: MCP-Server, Tools, Handler, Analytics und Sentry-Integration
• lib/: Next.js-kompatible Hilfsfunktionen (OAuth, Konfiguration, Fehlerbehandlung)
• mcp/utils/read-only.ts: schreibgeschützter Modus und Scope-Verarbeitung

Anleitungen

• Neon MCP Server Guide
• Connect MCP Clients to Neon
• Cursor with Neon MCP Server
• Claude Code with Neon MCP Server
• Claude Desktop with Neon MCP Server
• Cline with Neon MCP Server
• Windsurf with Neon MCP Server
• Zed with Neon MCP Server

Funktionen

Unterstützte Tools

Der Neon MCP Server stellt die folgenden Aktionen bereit, die MCP-Clients als „Tools“ zur Verfügung stehen. Mit diesen Tools kannst du über natürlichsprachliche Befehle mit deinen Neon-Projekten und -Datenbanken interagieren.

Metadaten zum Tool-Scope

Jede Tooldefinition enthält eine Kategorie scope, die für die grantbasierte Filterung von Tools und die Einwilligungs-UX verwendet wird. Aktuelle Kategorien:

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• realtime
• null (Tools ohne Scope-Kategorie: search, fetch, send_feedback)

Hinweise:

• Management-API-Tools stammen aus @neon/tools. Selektoren sind SDK-Pfade (projects.list); veröffentlichte MCP-Namen beginnen mit einem Verb (list_projects, delete_project, query_logs). Historische Namen bleiben dort erhalten, wo sie bereits verwendet wurden (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
• ?category=branches umfasst Branch-, Rollen- und Datenbank-Tools (list_postgres_roles, create_postgres_database, …). Ein bereits für branches ausgestelltes Token erhält diese Schreibzugriffe. Die Compute-Auflistung ist ?category=endpoints. Die Wiederherstellung eines Snapshots ist ?category=snapshots.
• Schreibzugriffe auf Projektmitglieder und Berechtigungen werden nicht veröffentlicht. list_project_members und list_project_permissions sind Lesezugriffe.
• Schema-Tools (?category=schema) sind get_database_tables und describe_table_schema sowie das generierte compare_database_schema.
• Die Durchsetzung des schreibgeschützten Modus stützt sich weiterhin auf readOnlySafe und serverseitige Logik für den schreibgeschützten Modus; scope sind Kategoriemetadaten und kein eigenständiger Lese-/Schreibschalter.
• Im projektbezogenen Modus (?projectId=...) werden Tools ohne Projektpfad (list_projects, count_projects, create_project, get_project_consumption, get_branch_consumption, list_organizations, list_regions, search, fetch, …) ausgeblendet. delete_project wird ebenfalls ausgeblendet.

Projektverwaltung:

• list_projects: Listet Neon-Projekte auf. limit begrenzt die Anzahl der zurückgegebenen Elemente.
• count_projects: Gibt die Anzahl der aktiven Projekte in einer Organisation zurück. org_id ist optional und wird wie bei list_projects aufgelöst.
• describe_project: Ruft ein Neon-Projekt anhand seiner ID ab ({ "project_id": "…" }).
• get_project_consumption, get_branch_consumption: Verbrauchsmetriken pro Projekt oder Branch, gruppiert nach Abrechnungszeitraum. Erfordern org_id, metrics, from, to und granularity sowie einen Launch-, Scale-, Agent-, Business- oder Enterprise-Tarif. get_branch_consumption erfordert außerdem project_ids, lehnt die Metriken extra_branches_month und snapshot_storage_bytes_month ab und ist im Business-Tarif nicht verfügbar. Der Endpunkt für ältere Tarife /consumption_history/projects wird nicht veröffentlicht.
• create_project: Erstellt ein Neon-Projekt und wartet auf die Standard-Compute-Instanz. Gibt keine Verbindungszeichenfolge zurück. Argumente sind { "name": "…", "org_id": "…", "region_id": "…" }. Rufe nach erfolgreichem Abschluss get_connection_string auf.
• delete_project: Löscht ein vorhandenes Neon-Projekt. Argumente sind { "project_id": "…" }.
• list_organizations: Listet alle Organisationen auf, auf die der aktuelle Benutzer Zugriff hat. Optional kannst du anhand des Suchparameters nach Organisationsname oder ID filtern.

Branch-Verwaltung:

• list_branches: Listet Branches in einem Projekt auf. Verwende es, um einen Branchnamen einer br-…-ID zuzuordnen.
• list_credentials, create_credential, revoke_credential, rotate_credential: Branchbezogene Anmeldedaten für Object Storage und das AI Gateway. reveal ist kein Tool; bei einer Rotation werden Geheimnisse direkt ersetzt, und der Vorgang ist nicht idempotent.
• create_branch: Erstellt einen Branch mit einer Lese-/Schreib-Compute-Instanz und wartet, bis sie bereit ist. Gibt keine Verbindungszeichenfolge zurück. Argumente sind { "project_id": "…", "name": "feature-x" }. Übergib no_compute: true, um den Endpunkt zu überspringen. Rufe nach erfolgreichem Abschluss get_connection_string auf.
• reset_from_parent: Setzt einen Branch auf den aktuellen HEAD seines übergeordneten Branches zurück ({ "project_id": "…", "branch_id": "br-…" }). Verwirft Schreibvorgänge seit der Abzweigung. preserve_under_name ist erforderlich, wenn der Branch untergeordnete Branches hat; diese werden auf den neuen Branch verschoben. Es wird nur der HEAD des übergeordneten Branches verwendet; für eine Wiederherstellung zu einem bestimmten Zeitpunkt siehe restore_snapshot.
• delete_branch: Löscht einen Branch ({ "project_id": "…", "branch_id": "br-…" }).
• describe_branch: Ruft einen Baum aus Datenbanken, Schemas, Tabellen, Views und Funktionen auf einem Branch ab.
• Generierte Branch-Tools erwarten branch_id als Branch-ID (br-...), nicht als Namen.
• restore_snapshot: Stellt einen Snapshot wieder her. Übergib target_branch_id, um ihn auf einem vorhandenen Branch wiederherzustellen; lasse es weg, um einen neuen Branch zu erstellen.

Compute-Endpunkte (?category=endpoints):

• list_postgres_endpoints, list_branch_computes, get_postgres_endpoint, create_postgres_endpoint, update_postgres_endpoint, delete_postgres_endpoint, start_postgres_endpoint, suspend_postgres_endpoint, restart_postgres_endpoint

Snapshots (?category=snapshots):

• list_snapshots, get_snapshot_schedule, set_snapshot_schedule, create_snapshot, update_snapshot, delete_snapshot, restore_snapshot

Schema (?category=schema):

• get_database_tables, describe_table_schema
• compare_database_schema: SQL-Schema-Diff einer Datenbank im Vergleich zu einer anderen Branch. database_name ist erforderlich. Wird base_branch_id weggelassen, erfolgt der Vergleich mit dem übergeordneten Branch. Die optionalen Parameter lsn, timestamp, base_lsn, base_timestamp gelten nur für einen bestimmten Zeitpunkt.

SQL-Abfrageausführung:

• get_connection_string: Gibt deine Datenbank-Verbindungszeichenfolge zurück.
• run_sql: Führt eine einzelne SQL-Abfrage für eine angegebene Neon-Datenbank aus. Unterstützt Lese- und Schreibvorgänge. Mit dem optionalen role_name wird die Anmeldung als diese Postgres-Rolle statt als Datenbankbesitzer durchgeführt, und mit compute_id wird die Compute-Instanz ausgewählt; die Anmeldedaten bleiben auf dem Server. Bei einer Verbindung mit ?roleName= muss role_name weggelassen werden oder damit übereinstimmen. Gibt das Zeilenarray mit höchstens max_rows Zeilen zurück (Standard: 100, maximal 10.000); wenn Zeilen abgeschnitten wurden, enthält ein zweiter Inhaltsblock { totalRowCount, truncated, note }. Bei einer fehlgeschlagenen Abfrage werden der Postgres-SQLSTATE, die Fehlerposition sowie alle Details, Hinweise oder Kontextinformationen zurückgegeben.
• run_sql_transaction: Führt eine Reihe von SQL-Abfragen innerhalb einer einzelnen Transaktion für eine Neon-Datenbank aus. Akzeptiert dieselben optionalen Parameter role_name, compute_id und max_rows wie run_sql. max_rows gilt pro Anweisung; wenn eine Anweisung abgeschnitten wurde, enthält der zweite Block eine Zusammenfassung pro Anweisung.
• get_database_tables: Listet alle Tabellen in einer angegebenen Neon-Datenbank auf.
• describe_table_schema: Ruft die Schemadefinition einer bestimmten Tabelle ab, einschließlich Spalten, Datentypen und Einschränkungen.

Datenbankmigrationen (Schemaänderungen):

• prepare_database_migration: Startet einen Datenbankmigrationsprozess. Dabei wird ein temporärer Branch erstellt, um die Migration sicher anzuwenden und zu testen, bevor der Haupt-Branch betroffen ist.
• complete_database_migration: Schließt eine vorbereitete Datenbankmigration ab und wendet sie auf den Haupt-Branch an. Diese Aktion führt Änderungen aus dem temporären Migrations-Branch zusammen und bereinigt temporäre Ressourcen.

SQL-Abfragen und Optimierung:

• inspect_database: Führt eine von 15 vordefinierten, schreibgeschützten Postgres-Diagnosen für einen Branch aus — Größen von Relationen und Indizes, Nutzung von Indizes und sequenziellen Scans, aktive Abfragen und Sperren, die aufwendigsten und häufigsten Abfragen, Cache-Trefferrate und Größe des Arbeitssatzes, Schätzungen zu Autovacuum und Bloat sowie Replikationsstatus. Entspricht denselben Prüfungen wie der CLI-Befehl neon inspect db. Lasse database_name weg, um alle Datenbanken im Branch abzudecken; gib einen Namen an, um eine einzelne Datenbank zu prüfen. Für vier Prüfungen ist die Erweiterung pg_stat_statements oder neon erforderlich.
• list_slow_queries: Ermittelt Leistungsengpässe, indem die langsamsten Abfragen in einer Datenbank gefunden werden. Erfordert die Erweiterung pg_stat_statements.
• explain_sql_statement: Stellt detaillierte Ausführungspläne für SQL-Abfragen bereit, um Leistungsengpässe zu erkennen.
• prepare_query_tuning: Analysiert die Abfrageleistung und schlägt Optimierungen vor, etwa das Erstellen von Indizes. Erstellt einen temporären Branch, um diese Optimierungen sicher zu testen.
• complete_query_tuning: Schließt die Abfrageoptimierung ab, indem Optimierungen entweder auf den Haupt-Branch angewendet oder verworfen werden. Bereinigt den temporären Optimierungs-Branch.

Neon Auth (?category=neon_auth):

• provision_neon_auth, get_auth, disable_auth, update_auth_config
• get_neon_auth_config: Geheimnisse werden geschwärzt. Liest vertrauenswürdige Ursprünge, localhost-Zugriff, E-Mail und Passwort, OAuth-Anbieter, den E-Mail-Anbieter, die Organisation, Magic Link und Telefon-Plugins, den Webhook sowie den Log-Export.
• update_auth_allow_localhost, update_auth_email_and_password, update_auth_email_provider, send_auth_test_email, update_auth_plugins_organization, update_auth_plugins_magic_link, update_auth_plugins_phone_number, update_auth_webhooks, update_auth_logs_export: Ändern diese Einstellungen. update_auth_webhooks ersetzt die gesamte Webhook-Konfiguration. update_auth_logs_export aktiviert oder deaktiviert den Export von Neon-Auth-Ereignissen in die Neon-Platform-Logs; bei einem Projekt ohne Log-Export wird nur enabled: false akzeptiert.
• list_auth_oauth_providers, add_auth_oauth_provider, update_auth_oauth_provider, delete_auth_oauth_provider
• get_auth_oauth_server, update_auth_oauth_server: Konfigurieren Neon Auth als OAuth-2.1-Autorisierungsserver (auch für MCP-Server). Unabhängig von den oben genannten Social-Login-Anbietern.
• list_auth_oauth_clients, get_auth_oauth_client, create_auth_oauth_client, update_auth_oauth_client, delete_auth_oauth_client, rotate_auth_oauth_client_secret: Verwalten die OAuth-Clients dieses Servers. create_auth_oauth_client und rotate_auth_oauth_client_secret geben den client_secret einmalig zurück.
• list_auth_trusted_domains, add_auth_trusted_domain, delete_auth_trusted_domain
• create_auth_user, delete_auth_user, update_auth_user_role

Neon Data API (?category=data_api):

• provision_neon_data_api, get_data_api, update_data_api, delete_data_api: Verwalten die Data API für eine Branch-Datenbank.

Suche und Entdeckung:

• search: Durchsucht Organisationen, Projekte und Branches nach einer passenden Suchanfrage. Gibt IDs, Titel und direkte Links zur Neon Console zurück.
• fetch: Ruft anhand einer ID detaillierte Informationen zu einer bestimmten Organisation, einem Projekt oder Branch ab (in der Regel aus dem Suchtool).

Feedback (immer verfügbar, auch über den nicht authentifizierten Endpunkt ?category=docs):

• send_feedback: Sendet anonymes Feedback an das Neon-Team. Es wird nur der Feedbacktext übermittelt, keine Konto-, Projekt- oder Verbindungsdetails. Nachrichten sind auf 10.000 Zeichen begrenzt.

Observability (?category=observability): Diese Tools erfordern die Neon Platform Beta und sind derzeit nur für Projekte in der Region aws-us-east-2 verfügbar. Ein Branch ohne Log-Zugriff gibt HTTP 404 mit dem Grund telemetry_not_enabled zurück.

• query_logs: Fragt OpenTelemetry-Logs für einen Branch ab. POST in der Management API; wird von diesem Server als schreibgeschützt behandelt.
• query_loki_logs: Führt eine LogQL-Bereichsabfrage über die Loki-kompatible Lese-API des Branches aus und gibt die Loki-Antwort zurück: nach Stream-Labels gruppierte Zeilen mit Zeitstempeln in Nanosekunden.
• list_log_fields: Listet die Log-Felder auf, für die Werte eines Branches aufgelistet werden können.
• list_log_field_values: Listet die unterschiedlichen Werte eines Log-Felds innerhalb eines Branches und Zeitfensters auf.

Dokumentation und Ressourcen (?category=docs):

• search_docs: Durchsucht neon.com (Dokumentation, API-Referenz, PostgreSQL-Tutorial, Anleitungen, FAQs, Änderungsprotokoll und Blog) mit derselben Suche wie das Suchfeld auf neon.com. Akzeptiert query, optional categories (docs, api, postgresql, guides, faqs, blog, changelog) und optional limit (1–40, Standard: 10). Gibt nach Relevanz sortierte Seiten mit title, url, slug, category, breadcrumb, heading und excerpt zurück; übergib slug an get_doc, um die Seite zu lesen.
• get_doc: Ruft eine neon.com-Seite als Markdown ab. Akzeptiert slug aus einem Treffer von search_docs (zum Beispiel docs/guides/prisma oder postgresql/tutorial/inner-join).

Funktionen (?category=functions):

• list_functions, get_function, update_function, delete_function, deploy_function
• list_functions_custom_domains, register_functions_custom_domain, delete_functions_custom_domain
• list_triggers, get_trigger, create_trigger, update_trigger, delete_trigger: Geplante Funktionsauslöser (type: "schedule", fünfteiliger UTC-Cron-Ausdruck).

Speicher (?category=storage):

• list_storage_buckets, create_storage_bucket, delete_storage_bucket
• list_storage_objects, delete_storage_object, delete_storage_objects_by_prefix
• presign_storage_object, get_storage

Realtime (?category=realtime):

• get_realtime, enable_realtime, disable_realtime: Realtime-Status des Branches, Aktivierung (optional allowed_origins) und Deaktivierung. Aktivierung und Deaktivierung warten, bis die Änderung angewendet wurde.
• get_realtime_secret: Das gemeinsame Geheimnis, mit dem das Anwendungs-Backend Realtime-Tokens ausstellt. Im schreibgeschützten Modus nicht verfügbar.
• rotate_realtime_secret: Ersetzt das gemeinsame Geheimnis und wartet, bis die Änderung angewendet wurde. Nicht idempotent. Rufe anschließend get_realtime_secret auf, um den neuen Wert abzurufen.

Migrationen

Migrationen dienen dazu, Änderungen am Datenbankschema im Laufe der Zeit zu verwalten. Mit dem Neon MCP-Server können LLMs Migrationen sicher durchführen, indem sie separate Befehle „Start“ (prepare_database_migration) und „Commit“ (complete_database_migration) verwenden.

Der Befehl „Start“ akzeptiert eine Migration und führt sie in einem neuen temporären Branch aus. Nach der Rückgabe weist dieser Befehl das LLM darauf hin, die Migration in diesem Branch zu testen. Anschließend kann das LLM den Befehl „Commit“ ausführen, um die Migration auf den ursprünglichen Branch anzuwenden.

Entwicklung

Dieses Projekt verwendet pnpm als Paketmanager, festgelegt über Corepack.

Projektstruktur

Der MCP-Server-Code befindet sich im Repository-Stammverzeichnis. Es handelt sich um eine Next.js-Anwendung, die unter mcp.neon.tech auf Vercel bereitgestellt wird.

corepack enable
pnpm install

Unter CONTRIBUTING.md erfährst du, wie du Tools hinzufügst. Tool-Argumente sind snake_case.

Lokale Entwicklung

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

Linting und Typprüfung

pnpm lint
pnpm typecheck

Umgebungsvariablen

Erforderlich für die Laufzeit des Remote-Servers:

Variable	Beschreibung
SERVER_HOST	Server-URL (Standardwert: VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL des Neon-OAuth-Anbieters
CLIENT_ID	OAuth-Client-ID
CLIENT_SECRET	OAuth-Client-Secret
KV_URL	Upstash-Redis-URL (Übergangssperre)
OAUTH_DATABASE_URL	Postgres-URL für die Token-Speicherung

Optional:

Variable	Beschreibung
LOG_LEVEL	Winston-Protokollstufe: error, warn, info (Standard), debug, verbose, silly
NEON_MCP_DISABLE_ANALYTICS	Auf 1 setzen, um Produktanalysen zu deaktivieren

Testpyramide

Alle Tests werden im Repository-Stammverzeichnis ausgeführt.

# 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

Teststrategie:

• E2E für Transport/Protokoll und für das nutzerseitig sichtbare Verhalten bevorzugen.
• Integrationstests für deterministische Tool-Verträge und Workflow-Verhalten verwenden.
• Unit-Tests für reine Logik und Randfälle verwenden.
• In Tests, die Merge-Entscheidungen beeinflussen, nicht von der Verfügbarkeit Dritter abhängig sein; externe Abhängigkeiten in den Integrations- und Unit-Teststufen mocken.

Bereitstellung

Vercel stellt den Remote-Server automatisch gemäß der Branch-Konfiguration des Repositorys bereit. Für Pull Requests stehen Vorschauumgebungen zur Verfügung.

Telemetrie

Der Neon MCP-Server erfasst Produktanalysen und Fehlerberichte, damit wir die Nutzung besser verstehen und die Zuverlässigkeit verbessern können:

• Produktanalysen (Segment): Wenn du dich mit einem authentifizierten Konto verbindest, sendet der Server ein identify-Ereignis mit deiner Neon-Konto-ID, deinem Namen und deiner E-Mail-Adresse. Außerdem werden der Sitzungsstart (server_init), jeder Tool-Aufruf (tool_call) und unerwartete Serverfehler (server_error) erfasst. Ein Tool-Aufruf-Ereignis enthält den Tool-Namen, die Authentifizierungsmethode und den Client, jedoch weder Tool-Argumente noch Abfrageergebnisse. Aufrufe von Tools, die nur die Dokumentation betreffen und ohne Konto erfolgen, werden anonym erfasst. Die nach der Autorisierung angezeigte Seite meldet, dass sie angezeigt wurde (auth_complete_viewed, einschließlich Ergebnis und Client) und welche Schaltflächen und Links verwendet wurden (auth_complete_action); der Browser sendet lediglich eine zufällige Seitenaufruf-ID, niemals den Autorisierungscode oder deine Identität. Ereignisse werden an track.neon.tech, den eigenen Analyse-Endpunkt von Neon, gesendet.
• Fehlerberichte, Traces und Logs (Sentry): Unerwartete Serverfehler werden zusammen mit Stacktraces sowie der Methode und dem Pfad der Anfrage gemeldet. Anfrage-Header, -Bodies, Cookies und Query-Strings werden nicht gesendet. Für jede Anfrage und jeden Tool-Aufruf wird ein Trace mit Tool-Namen, Client-Namen, Konto-ID und Angabe, ob der Aufruf fehlgeschlagen ist, erstellt. Außerdem enthält er die Sitzungs-ID, die der Server Clients aus dem Jahr 2025 zuweist, sowie die Konversations-ID, die ein Client in _meta.threadId sendet. Traces enthalten keine Tool-Argumente oder -Ergebnisse. Auch die Server-Logs werden an Sentry gesendet. Diese Sammlung unterliegt der Neon-Datenschutzerklärung. Um Analytics zu deaktivieren, wenn du den Server selbst ausführst, setze NEON_MCP_DISABLE_ANALYTICS=1. Dieses Flag deaktiviert Sentry nicht.