Neon

Neon MCP Server

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

Das Model Context Protocol (MCP) ist ein standardisiertes Protokoll, das entwickelt wurde, um 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. Aufbauend auf MCP übersetzt er Ihre Anfragen in die erforderlichen API-Aufrufe und ermöglicht es Ihnen, Aufgaben wie das Erstellen von Projekten und Branches, das Ausführen von Abfragen und die Durchführung von Datenbankmigrationen nahtlos zu 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 von Datenbankmigrationen: Nutzen Sie die Branching-Funktionen von Neon für Datenbankschemaänderungen, die über natürliche Sprache initiiert werden.

In Claude Code oder einem beliebigen MCP-Client können Sie beispielsweise natürliche Sprache verwenden, um mit Neon Dinge zu erreichen, wie:

• 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 gewährt leistungsstarke Datenbankverwaltungsfunktionen durch Anfragen in natürlicher Sprache. Überprüfen und autorisieren Sie immer die vom LLM angeforderten Aktionen, bevor Sie sie ausführen. Stellen Sie sicher, dass nur autorisierte Benutzer und Anwendungen Zugriff auf den Neon MCP Server haben.

Der Neon MCP Server ist nur für die lokale Entwicklung und IDE-Integrationen vorgesehen. Wir empfehlen nicht, den Neon MCP Server in Produktionsumgebungen zu verwenden. Er kann leistungsstarke Operationen ausführen, die zu versehentlichen oder unbefugten Änderungen führen können.

Weitere Informationen finden Sie unter MCP-Sicherheitsleitfaden →.

Einrichten des Neon MCP Servers

Es gibt mehrere Optionen zum Einrichten des Neon MCP Servers:

1. Schnelleinrichtung mit API-Schlüssel (Cursor, VS Code und Claude Code): Führen Sie neonctl@latest init aus, um den MCP-Server von Neon, Agent Skills und die VS Code-Erweiterung mit einem Befehl automatisch zu konfigurieren.
2. Remote MCP Server (OAuth-basierte Authentifizierung): Stellen Sie eine Verbindung zum verwalteten MCP-Server von Neon her, indem Sie OAuth zur Authentifizierung verwenden. Diese Methode ist bequemer, da die Verwaltung von API-Schlüsseln entfällt. 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 eine Verbindung zum verwalteten MCP-Server von Neon her, indem Sie einen API-Schlüssel zur Authentifizierung verwenden. Diese Methode ist nützlich, wenn Sie einen Remote-Agenten mit Neon verbinden möchten, bei dem 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 von 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 neonctl@latest init aus, um den MCP-Server von Neon automatisch mit einem Befehl zu konfigurieren:

npx neonctl@latest init

Dies funktioniert mit Cursor, VS Code (GitHub Copilot) und Claude Code. Es authentifiziert sich über OAuth, erstellt einen Neon-API-Schlüssel für Sie und konfiguriert Ihren Editor automatisch.

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

Stellen Sie eine Verbindung zum verwalteten MCP-Server von Neon her, indem Sie OAuth zur Authentifizierung verwenden. Dies ist die einfachste Einrichtung, erfordert keine lokale Installation dieses Servers und benötigt 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

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

Alternativ können Sie den folgenden „Neon“-Eintrag 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"
    }
  }
}

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

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

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

• Starten Sie Ihren MCP-Client neu oder aktualisieren Sie ihn.
• Ein OAuth-Fenster öffnet sich in Ihrem Browser. Befolgen Sie die Anweisungen, um Ihren MCP-Client für den Zugriff auf Ihr Neon-Konto zu autorisieren.

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

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

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

Erstellen Sie einen Neon-API-Schlüssel in der Neon-Konsole. Führen Sie als Nächstes 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 --header "Authorization: Bearer <$NEON_API_KEY>"

Alternativ können Sie den folgenden „Neon“-Eintrag 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",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

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

Bereiche und Nur-Lese-Modus

Neon MCP unterstützt die OAuth-Bereiche read, write und * (* bedeutet beides). Ihr MCP-Client kann diese Bereiche direkt anfordern, oder Sie können die Auswahl in der OAuth-Berechtigungsbenutzeroberfläche treffen.

Der Nur-Lese-Modus schränkt ein, welche Tools verfügbar sind, und deaktiviert Schreiboperationen wie das Erstellen von Projekten, 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 Nur-Lese-Modus auf zwei Arten festlegen:

1. OAuth-Bereichsauswahl (empfohlen): Wählen Sie in OAuth den Nur-Lese-Modus, indem Sie Vollzugriff in der Autorisierungsoberfläche deaktivieren.
2. readonly-Abfrageparameter: Fügen Sie ?readonly=true zu Ihrer MCP-Server-URL hinzu:

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

Verhalten des Abfrageparameters:

• API-Schlüssel-Flow: readonly=true ist die Möglichkeit, den Nur-Lese-Modus zu aktivieren (in diesem Flow findet kein OAuth-Bereichsaustausch statt).
• OAuth-Flow: readonly=true überschreibt den OAuth-Bereich. Ohne diesen wird der Nur-Lese-Modus durch den in der OAuth-Zustimmungsbenutzeroberfläche ausgewählten Bereich bestimmt.

Der veraltete HTTP-Header x-read-only wird ebenfalls als Fallback unterstützt (niedrigere Priorität als der Abfrageparameter).

Hinweis: Der Nur-Lese-Modus schränkt ein, welche Tools verfügbar sind. Darüber hinaus bleibt das Tool run_sql nur für schreibgeschützte Abfragen verfügbar.

URL-Abfrageparameter für die Zugriffskontrolle

Der Gewährungskontext (Bereichskategorien, Projektbezug, Nur-Lese-Modus) wird über URL-Abfrageparameter in der MCP-Server-URL konfiguriert. Die Konfiguration wird mit jeder Anfrage übertragen und tritt sofort in Kraft – keine erneute Authentifizierung erforderlich.

Parameter	Beschreibung	Beispiel
readonly	Nur-Lese-Modus aktivieren (true/false)	?readonly=true
category	Auf bestimmte Tool-Kategorien beschränken (wiederholt oder CSV)	?category=querying&category=schema
projectId	Alle Operationen auf ein einzelnes Projekt beschränken	?projectId=proj-123

Beispiel für Nur-Lese-Modus + Projektbezug:

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

Beispiel für Kategoriefilterung (nur Abfrage- und Schema-Tools):

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

Sie können eine Vorschau der für eine beliebige Konfiguration sichtbaren Tools mit dem Endpunkt /api/list-tools anzeigen (keine Authentifizierung erforderlich):

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

Im Nur-Lese-Modus verfügbare Tools

• 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

Tools, die Schreibzugriff erfordern:

• 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

Server-Sent Events (SSE) Transport (Veraltet)

MCP unterstützt zwei Remote-Server-Transporte: die veralteten Server-Sent Events (SSE) und das neuere, empfohlene Streamable HTTP. Wenn Ihr LLM-Client Streamable HTTP noch nicht unterstützt, können Sie den Endpunkt von https://mcp.neon.tech/mcp auf https://mcp.neon.tech/sse umstellen, um stattdessen SSE zu verwenden.

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

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

Remote-Server-Architektur

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

[!NOTE] Der Root-Pfad / leitet zur Neon MCP Server-Dokumentation weiter. Es gibt keine Landingpage.

Kernbereiche der Implementierung:

• app/api/[transport]/route.ts: MCP-Transportendpunkt für Streamable HTTP (/mcp) und SSE (/sse)
• 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, Analytik und Sentry-Integration
• lib/: Next.js-kompatible Hilfsprogramme (OAuth, Konfiguration, Fehlerbehandlung)
• mcp/utils/read-only.ts: Nur-Lese-Modus und Bereichsbehandlung

Anleitungen

• Neon MCP Server-Anleitung
• MCP-Clients mit Neon verbinden
• Cursor mit Neon MCP Server
• Claude Desktop mit Neon MCP Server
• Cline mit Neon MCP Server
• Windsurf mit Neon MCP Server
• Zed mit Neon MCP Server

Funktionen

Unterstützte Tools

Der Neon MCP Server bietet die folgenden Aktionen, die MCP-Clients als „Tools“ zur Verfügung gestellt werden. Sie können diese Tools verwenden, um mit Ihren Neon-Projekten und -Datenbanken über Befehle in natürlicher Sprache zu interagieren.

Tool-Bereichsmetadaten

Jede Tool-Definition enthält eine scope-Kategorie, die für die berechtigungsbasierte Tool-Filterung und die Zustimmungs-UX verwendet wird. Aktuelle Kategorien sind:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• docs
• null (Tools ohne Bereichskategorie)

Hinweise:

• compare_database_schema ist unter schema kategorisiert.
• provision_neon_data_api ist unter data_api kategorisiert (getrennt von neon_auth).
• Die Durchsetzung des Nur-Lese-Modus basiert weiterhin auf readOnlySafe und der serverseitigen Nur-Lese-Logik; scope sind Kategorienmetadaten, kein eigenständiger Lese-/Schreibschalter.
• Im projektbezogenen Modus (?projectId=...) sind search und fetch nicht verfügbar.

Projektverwaltung:

• list_projects: Listet die ersten 10 Neon-Projekte in Ihrem Konto auf und bietet eine Zusammenfassung jedes Projekts. Wenn Sie ein bestimmtes Projekt nicht finden können, erhöhen Sie das Limit, indem Sie einen höheren Wert an den Parameter limit übergeben.
• list_shared_projects: Listet Neon-Projekte auf, die für den aktuellen Benutzer freigegeben sind. Unterstützt einen Suchparameter und die Begrenzung der Anzahl zurückgegebener Projekte (Standard: 10).
• describe_project: Ruft detaillierte Informationen zu einem bestimmten Neon-Projekt ab, einschließlich seiner ID, seines Namens und der zugehörigen Branches und Datenbanken.
• create_project: Erstellt ein neues Neon-Projekt in Ihrem Neon-Konto. Ein Projekt fungiert als Container für Branches, Datenbanken, Rollen und Computes.
• delete_project: Löscht ein bestehendes Neon-Projekt und alle zugehörigen Ressourcen.
• list_organizations: Listet alle Organisationen auf, auf die der aktuelle Benutzer Zugriff hat. Optional kann mit dem Suchparameter nach Organisationsname oder -ID gefiltert werden.

Branch-Verwaltung:

• create_branch: Erstellt einen neuen Branch innerhalb eines angegebenen Neon-Projekts. Nutzt die Branching-Funktion von Neon für Entwicklung, Tests oder Migrationen.
• delete_branch: Löscht einen bestehenden Branch aus einem Neon-Projekt.
• describe_branch: Ruft Details zu einem bestimmten Branch ab, wie Name, ID und übergeordneten Branch.
• list_branch_computes: Listet Compute-Endpunkte für ein Projekt oder einen bestimmten Branch auf, einschließlich Compute-ID, Typ, Größe, letzter Aktivitätszeit und Autoscaling-Informationen.
• compare_database_schema: Zeigt den Schema-Unterschied zwischen dem untergeordneten Branch und seinem übergeordneten Branch an.
• reset_from_parent: Setzt den aktuellen Branch auf den Zustand seines übergeordneten Branches zurück und verwirft lokale Änderungen. Sichert automatisch in ein Backup, wenn der Branch untergeordnete Branches hat, oder optional auf Anfrage mit einem benutzerdefinierten Namen.

SQL-Abfrageausführung:

• get_connection_string: Gibt Ihre Datenbank-Verbindungszeichenfolge zurück.
• run_sql: Führt eine einzelne SQL-Abfrage für eine angegebene Neon-Datenbank aus. Unterstützt sowohl Lese- als auch Schreiboperationen.
• run_sql_transaction: Führt eine Reihe von SQL-Abfragen innerhalb einer einzigen Transaktion für eine Neon-Datenbank aus.
• get_database_tables: Listet alle Tabellen innerhalb einer angegebenen Neon-Datenbank auf.
• describe_table_schema: Ruft die Schemadefinition einer bestimmten Tabelle ab und beschreibt Spalten, Datentypen und Einschränkungen.

Datenbankmigrationen (Schemaänderungen):

• prepare_database_migration: Initiiert einen Datenbankmigrationsprozess. Entscheidend ist, dass ein temporärer Branch erstellt wird, 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:

• list_slow_queries: Identifiziert Leistungsengpässe, indem die langsamsten Abfragen in einer Datenbank gefunden werden. Erfordert die Erweiterung pg_stat_statements.
• explain_sql_statement: Bietet detaillierte Ausführungspläne für SQL-Abfragen, um Leistungsengpässe zu identifizieren.
• prepare_query_tuning: Analysiert die Abfrageleistung und schlägt Optimierungen vor, wie z. B. die Erstellung von Indizes. Erstellt einen temporären Branch zum sicheren Testen dieser Optimierungen.
• 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:

• provision_neon_auth: Stellt Neon Auth für ein Neon-Projekt bereit. Ermöglicht Entwicklern die einfache Einrichtung einer Authentifizierungsinfrastruktur durch Erstellen einer Integration mit einem Auth-Anbieter.

Neon Data API:

• provision_neon_data_api: Stellt die Neon Data API für HTTP-basierten Datenbankzugriff mit optionaler JWT-Authentifizierung über Neon Auth oder externe JWKS-Anbieter bereit.

Suche und Erkennung:

• search: Durchsucht Organisationen, Projekte und Branches, die einer Abfrage entsprechen. Gibt IDs, Titel und direkte Links zur Neon-Konsole zurück.
• fetch: Ruft detaillierte Informationen zu einer bestimmten Organisation, einem Projekt oder einem Branch anhand einer ID ab (in der Regel aus dem Suchwerkzeug).

Dokumentation und Ressourcen:

• list_docs_resources: Listet alle verfügbaren Neon-Dokumentationsseiten auf, indem der Index von https://neon.com/docs/llms.txt abgerufen wird. Gibt Seiten-URLs und Titel zurück, die einzeln mit dem Werkzeug get_doc_resource abgerufen werden können.
• get_doc_resource: Ruft eine bestimmte Neon-Dokumentationsseite als Markdown-Inhalt ab. Verwenden Sie zuerst das Werkzeug list_docs_resources, um verfügbare Seiten-Slugs zu ermitteln, und übergeben Sie dann den Slug an dieses Werkzeug.

Migrationen

Migrationen sind eine Möglichkeit, Änderungen an Ihrem Datenbankschema im Laufe der Zeit zu verwalten. Mit dem Neon MCP-Server können LLMs Migrationen sicher mit separaten „Start“- (prepare_database_migration) und „Commit“-Befehlen (complete_database_migration) durchführen.

Der „Start“-Befehl akzeptiert eine Migration und führt sie in einem neuen temporären Branch aus. Nach der Rückkehr weist dieser Befehl das LLM darauf hin, dass es die Migration auf diesem Branch testen sollte. Das LLM kann dann den „Commit“-Befehl ausführen, um die Migration auf den ursprünglichen Branch anzuwenden.

Entwicklung

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

Projektstruktur

Der MCP-Servercode befindet sich im Repository-Stammverzeichnis, einer Next.js-Anwendung, die auf Vercel unter mcp.neon.tech bereitgestellt wird.

corepack enable
pnpm install

Lokale Entwicklung

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

Linting und Typprüfung

pnpm run lint
pnpm run typecheck

Umgebungsvariablen

Erforderlich für die Remote-Server-Laufzeit:

Variable	Beschreibung
SERVER_HOST	Server-URL (Standard: VERCEL_URL)
UPSTREAM_OAUTH_HOST	Neon OAuth-Anbieter-URL
CLIENT_ID	OAuth-Client-ID
CLIENT_SECRET	OAuth-Client-Geheimnis
COOKIE_SECRET	Geheimnis für signierte Cookies
KV_URL	Vercel KV (Upstash Redis) URL
OAUTH_DATABASE_URL	Postgres-URL für Token-Speicherung

Optional:

Variable	Beschreibung
LOG_LEVEL	Winston-Protokollstufe: error, warn, info (Standard), debug, verbose, silly

Testpyramide

Alle Tests werden vom Repository-Stammverzeichnis aus ausgeführt.

# 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

Teststrategie:

• Bevorzugen Sie E2E für Transport/Protokoll und benutzersichtbares Verhalten.
• Verwenden Sie Integrationstests für deterministische Werkzeugverträge und Workflow-Verhalten.
• Verwenden Sie Unit-Tests für reine Logik und Randfälle.
• Vermeiden Sie es, sich bei Merge-Gating-Tests auf die Betriebszeit von Drittanbietern zu verlassen; simulieren Sie externe Abhängigkeiten in den Integrations-/Unit-Ebenen.

Bereitstellung

Vercel stellt den Remote-Server automatisch aus der Repository-Branch-Konfiguration bereit. Vorschau-Umgebungen sind für Pull Requests verfügbar.