Neon MCP Server

The Neon MCP Server provides comprehensive integration with Neon's serverless Postgres platform, enabling AI assistants to manage database projects, execute queries, perform schema migrations, optimize query performance, and provision authentication—all through natural language interactions. This server transforms complex database operations into simple conversational workflows, making database management accessible while maintaining safety through features like temporary branch testing and automated rollback capabilities.

Overview

Neon is a serverless Postgres platform that separates storage and compute, offering instant provisioning, automatic scaling, and branching capabilities similar to Git. This MCP server exposes Neon's powerful API and database operations as tools that AI assistants can use to help developers manage their database infrastructure, write and optimize SQL queries, perform schema migrations safely, and set up authentication systems.

The server handles everything from project creation and management to advanced operations like query tuning with execution plan analysis, safe schema migrations using temporary branches, and Stack Auth integration for authentication. Whether you're creating a new database, analyzing slow queries, or performing complex schema changes, the Neon MCP Server provides the tools to accomplish these tasks through conversational AI.

Key Features

Project and Organization Management

The server provides comprehensive control over Neon projects and organizations. You can list all projects in your account with support for pagination and filtering by name or ID. The search functionality allows you to quickly find specific projects, and you can scope searches to particular organizations. Projects can be created with custom names and assigned to specific organizations, making it easy to organize your database infrastructure. The server also supports listing shared projects that other users have granted you access to, facilitating team collaboration.

Branch Management and Git-like Workflows

One of Neon's most powerful features is database branching, which this server fully supports. You can create branches of your database for testing, development, or staging purposes. Each branch is an isolated copy-on-write clone that shares the parent's data until modifications are made. The server enables you to describe branch contents, delete branches when no longer needed, and reset branches from their parent to discard changes and start fresh. The reset operation optionally preserves the current state under a new branch name, preventing accidental data loss.

SQL Query Execution

Execute SQL queries directly against your Neon databases through simple tool calls. The server supports both single SQL statements and multi-statement transactions, ensuring atomicity for complex operations. You can target specific branches for testing without affecting production data, and optionally specify custom database names and roles. This flexibility makes it easy to test queries safely before running them in production environments.

Schema Inspection and Discovery

Understanding your database structure is essential for effective management. The server provides tools to discover all tables in a database, describe detailed table schemas including columns, data types, constraints, and indexes, and get comprehensive tree views of branch contents showing all databases, schemas, tables, views, and functions. This introspection capability helps AI assistants understand your database structure and provide accurate assistance.

Safe Schema Migrations

Database schema changes are risky operations that can cause data loss or downtime if not handled carefully. The Neon MCP Server implements a two-phase migration workflow that maximizes safety. First, the prepare_database_migration tool creates a temporary branch and applies your migration there. You can then test the changes thoroughly using SQL queries against the temporary branch. The tool accepts natural language migration requests like "Add email column to users table" or "Create posts table with title and content columns" and generates the appropriate SQL DDL statements.

After verification, the complete_database_migration tool applies the changes to your main branch and cleans up the temporary branch. If testing reveals issues, you can simply reject the migration, and the temporary branch is deleted without affecting production data. The system automatically retries failed operations once and provides detailed error information if problems persist.

Query Performance Optimization

Slow queries can significantly impact application performance. The server includes sophisticated query tuning capabilities that help identify and resolve performance bottlenecks. The prepare_query_tuning tool analyzes your SQL query by examining its execution plan, extracting all referenced tables, gathering detailed schema information, and suggesting optimizations like adding indexes, restructuring queries, or identifying bottlenecks.

Like migrations, query tuning uses a temporary branch for testing. The tool applies suggested changes to the temporary branch, allowing you to compare performance before and after optimization. You can then use complete_query_tuning to apply approved changes to your main branch or discard them if they don't provide sufficient improvement. The server also provides a list_slow_queries tool that identifies problematic queries by querying the pg_stat_statements extension, showing queries sorted by execution time with configurable thresholds.

Query Execution Plan Analysis

Understanding how Postgres executes your queries is crucial for optimization. The explain_sql_statement tool runs EXPLAIN (ANALYZE) on your queries, providing detailed execution plans that show table scans, index usage, join methods, and cost estimates. This information helps identify why queries are slow and what optimizations might help.

Authentication Provisioning

Modern applications require robust authentication systems, but setting them up can be complex and time-consuming. The provision_neon_auth tool automates authentication infrastructure setup by creating an integration with Stack Auth. The tool establishes a connection between your Neon project and Stack Auth, creates a dedicated authentication schema in your database, sets up synchronized user tables, and generates client and secret keys for your application.

The server provides comprehensive Stack Auth integration guidelines, including setup instructions for Next.js applications, component usage patterns for sign-in and user management, client and server component examples, and page protection strategies using middleware or hooks. This automation eliminates hours of manual configuration and ensures best practices are followed.

Connection String Management

Connecting to your Neon databases requires properly formatted connection strings with correct credentials and endpoints. The get_connection_string tool generates PostgreSQL connection strings with all necessary parameters, supporting custom branches, roles, compute endpoints, and database names. All parameters are optional, with sensible defaults for common use cases.

Tools

list_projects

Lists the first 10 Neon projects in your account with support for pagination through cursor-based navigation. You can increase the limit up to 400 projects per request and filter results by project name or ID using partial matching. The tool also supports filtering by organization ID to scope results to specific organizations.

Parameters:

• limit (number, default: 10): Number of projects to return (1-400)
• cursor (string, optional): Pagination cursor from previous response
• org_id (string, optional): Filter by organization ID
• search (string, optional): Filter by project name or ID (supports partial matching)

list_organizations

Lists all organizations that the current user has access to, with optional filtering by organization name or ID using partial matching. This helps you understand your organization structure and scope other operations appropriately.

Parameters:

• search (string, optional): Filter by organization name or ID (supports partial matching)

list_shared_projects

Lists projects that other users have shared with you, enabling collaboration on databases. Supports pagination and filtering by project name or ID, similar to the regular project listing.

Parameters:

• limit (number, default: 10): Number of shared projects to return (1-400)
• cursor (string, optional): Pagination cursor from previous response
• search (string, optional): Filter by project name or ID (supports partial matching)

create_project

Creates a new Neon project with optional custom name and organization assignment. If someone requests a database, this tool handles the creation. The newly created project includes a default branch with a Postgres database ready for use.

Parameters:

• name (string, optional): Custom project name
• org_id (string, optional): Organization ID to create the project in

delete_project

Permanently deletes a Neon project and all its associated data, including all branches, databases, and backups. This operation cannot be undone, so use with caution.

Parameters:

• projectId (string, required): ID of the project to delete

describe_project

Retrieves detailed information about a specific Neon project, including configuration, region, branches, and resource usage. This provides a comprehensive view of the project's current state.

Parameters:

• projectId (string, required): ID of the project to describe

run_sql

Executes a single SQL statement against a Neon database. You can target specific branches for testing, specify custom database names, and use different roles. The tool is particularly useful for testing migrations in temporary branches.

Parameters:

• sql (string, required): SQL query to execute
• projectId (string, required): Project ID
• branchId (string, optional): Branch ID (defaults to main branch)
• databaseName (string, optional): Database name (defaults to neondb or first available)

run_sql_transaction

Executes multiple SQL statements as a single atomic transaction, ensuring all statements succeed or all fail together. This is essential for complex operations that must maintain database consistency.

Parameters:

• sqlStatements (array of strings, required): SQL statements to execute
• projectId (string, required): Project ID
• branchId (string, optional): Branch ID (defaults to main branch)
• databaseName (string, optional): Database name (defaults to neondb or first available)

describe_table_schema

Retrieves comprehensive schema information for a specific table, including column definitions with data types and constraints, primary and foreign keys, indexes, and check constraints. This helps understand table structure for queries and migrations.

Parameters:

• tableName (string, required): Name of the table
• projectId (string, required): Project ID
• branchId (string, optional): Branch ID (defaults to main branch)
• databaseName (string, optional): Database name (defaults to neondb or first available)

get_database_tables

Lists all tables in a database, providing an overview of the database structure. This is useful for discovery and understanding what data exists.

Parameters:

• projectId (string, required): Project ID
• branchId (string, optional): Branch ID (defaults to main branch)
• databaseName (string, optional): Database name (defaults to neondb or first available)

create_branch

Creates a new branch from an existing branch (defaults to main). Branches are copy-on-write clones that share the parent's data initially, making them fast to create and storage-efficient until modifications occur.

Parameters:

• projectId (string, required): Project ID
• branchName (string, optional): Custom branch name

prepare_database_migration

Initiates a safe two-phase migration workflow by creating a temporary branch, generating SQL DDL from natural language requests, and applying changes to the test branch. Supports CREATE, ALTER, and DROP operations for tables, columns, constraints, and indexes. The tool automatically retries once on failure and provides detailed error information.

Parameters:

• migrationSql (string, required): SQL DDL statements to execute
• projectId (string, required): Project ID
• databaseName (string, optional): Database name (defaults to neondb or first available)

complete_database_migration

Completes a migration by applying verified changes to the main branch and cleaning up the temporary branch. This tool must be called even when migrations are rejected to ensure proper cleanup. It requires the migration ID from the prepare phase.

Parameters:

• migrationId (string, required): Migration ID from prepare phase

describe_branch

Provides a comprehensive tree view of all objects in a branch, including databases, schemas, tables, views, functions, and their relationships. This gives a complete picture of the branch structure.

Parameters:

• projectId (string, required): Project ID
• branchId (string, required): Branch ID
• databaseName (string, optional): Database name (defaults to neondb or first available)

delete_branch

Permanently deletes a branch and all its associated data. This cannot be undone, so ensure the branch is no longer needed before deletion.

Parameters:

• projectId (string, required): Project ID
• branchId (string, required): Branch ID to delete

reset_from_parent

Resets a branch to match its parent's current state, discarding all changes. Optionally preserves the current state under a new branch name before resetting, preventing data loss. This is useful for creating fresh development branches or undoing experimental changes.

Parameters:

• projectId (string, required): Project ID
• branchIdOrName (string, required): Branch ID or name to reset
• preserveUnderName (string, optional): Name for preserving current state as new branch

get_connection_string

Generates a properly formatted PostgreSQL connection string with all necessary parameters for connecting to your Neon database. All parameters are optional with sensible defaults.

Parameters:

• projectId (string, required): Project ID
• branchId (string, optional): Branch ID or name (defaults to main branch)
• roleName (string, optional): Role name (defaults to database owner)
• computeId (string, optional): Compute endpoint ID (defaults to read-write compute)
• databaseName (string, optional): Database name (defaults to neondb or first available)

provision_neon_auth

Automates authentication infrastructure setup by integrating with Stack Auth. Creates authentication schemas, sets up user tables, and generates API keys. Includes comprehensive Stack Auth setup guidelines for Next.js applications with component usage examples and best practices.

Parameters:

• projectId (string, required): Project ID
• database (string, optional): Database name (defaults to neondb or first available)

explain_sql_statement

Analyzes SQL query execution plans using EXPLAIN (ANALYZE) to understand query performance. Shows table scans, index usage, join methods, cost estimates, and actual execution times. Essential for identifying optimization opportunities.

Parameters:

• sql (string, required): SQL statement to analyze
• projectId (string, required): Project ID
• analyze (boolean, default: true): Include ANALYZE in EXPLAIN command
• branchId (string, optional): Branch ID (defaults to main branch)
• databaseName (string, optional): Database name (defaults to neondb or first available)

prepare_query_tuning

Initiates query performance optimization by creating a temporary branch, analyzing execution plans, gathering schema information for all referenced tables, suggesting improvements like indexes or query restructuring, and applying changes to the test branch for verification. Automatically retries once on failure.

Parameters:

• sql (string, required): SQL statement to optimize
• projectId (string, required): Project ID
• databaseName (string, required): Database name
• roleName (string, optional): Role name (defaults to neondb_owner)

complete_query_tuning

Completes query optimization by applying approved changes to the main branch or specified branch and cleaning up the temporary branch. Must be called even when changes are rejected to ensure proper cleanup. Requires the tuning ID from the prepare phase.

Parameters:

• tuningId (string, required): Tuning ID from prepare phase
• projectId (string, required): Project ID
• databaseName (string, required): Database name
• temporaryBranchId (string, required): Temporary branch ID to clean up
• suggestedSqlStatements (array of strings, required): SQL DDL statements to apply
• applyChanges (boolean, default: false): Whether to apply changes to main branch
• branchId (string, optional): Target branch (defaults to main branch)
• roleName (string, optional): Role name (defaults to neondb_owner)
• shouldDeleteTemporaryBranch (boolean, default: true): Whether to delete temporary branch

list_slow_queries

Identifies slow-running queries by querying the pg_stat_statements extension. Returns queries sorted by execution time with configurable minimum execution time thresholds and result limits. Essential for proactive performance monitoring.

Parameters:

• projectId (string, required): Project ID
• limit (number, default: 10): Maximum number of queries to return
• minExecutionTime (number, default: 1000): Minimum execution time in milliseconds
• branchId (string, optional): Branch ID (defaults to main branch)
• computeId (string, optional): Compute endpoint ID (defaults to read-write compute)
• databaseName (string, optional): Database name (defaults to neondb or first available)

list_branch_computes

Lists compute endpoints for a project or specific branch, showing available compute resources for connections. Compute endpoints represent the actual Postgres instances serving queries.

Parameters:

• projectId (string, optional): Project ID (defaults to only available project)
• branchId (string, optional): Branch ID (shows endpoints for specific branch)

Use Cases

The Neon MCP Server enables numerous practical workflows:

Database Setup and Management: Create new projects for different applications or environments, organize projects within teams using organizations, share database access with collaborators, and manage the complete lifecycle from creation to deletion.

Safe Schema Evolution: Test schema changes in isolated branches before production deployment, use natural language to describe desired changes without writing DDL manually, verify migrations thoroughly before committing to main branch, and automatically rollback if issues are discovered during testing.

Performance Optimization: Identify slow queries affecting application performance, analyze execution plans to understand query behavior, receive AI-generated optimization suggestions based on schema analysis, test optimizations in temporary branches, and apply proven improvements to production with confidence.

Development Workflows: Create feature branches for developing new functionality with database changes, test database-dependent features in isolation, reset development branches from updated production data, and collaborate on database changes through shared projects.

Authentication Integration: Set up complete authentication infrastructure in minutes rather than hours, integrate with modern authentication providers like Stack Auth, follow best practices automatically through provided guidelines, and get working code examples for common authentication patterns.

Getting Started

To use the Neon MCP Server, you'll need a Neon account with valid API credentials. Once configured, AI assistants can immediately begin helping with database tasks through natural conversation. Ask questions like "Show me my Neon projects," "Create a new database for my blog application," "Add an email column to the users table," or "Why is this query slow and how can I optimize it?"

The server handles all the complexity of API calls, SQL generation, branch management, and safety checks, allowing you to focus on your application logic while maintaining database best practices.