Neon MCP Server

How to use

You connect a compatible MCP client to Neon using either a remote managed MCP server or a local Neon MCP server running on your machine. Once connected, you can ask the system to create projects and branches, run queries, manage migrations, and fetch summaries of your Neon resources. Use natural language prompts to describe what you want to do, and the MCP server will translate your request into the appropriate Neon operations.

How to install

Prerequisites you need before installation.

- An MCP Client application.

- A Neon account.

- Node.js (>= v18.0.0). Download from nodejs.org.

For Local MCP Server setup, you also need a Neon API key. See Neon API Keys documentation for instructions on generating one.

For development, you’ll also need Bun installed.

Choose one of the two connection options below.

Option 1. Remote Hosted MCP Server (Preview) Connect to Neon's managed MCP server using OAuth for authentication. This is the easiest setup, requires no local installation of this server, and doesn't need a Neon API key configured in the client.

Add the Neon entry to your MCP client configuration file (mcp.json or mcp_config.json) as shown in the snippet.

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

Option 2. Local MCP Server

Run the Neon MCP server locally with your Neon API key.

Add the following JSON configuration within the mcpServers section of your client’s mcp_config file, replacing <YOUR_NEON_API_KEY> with your actual Neon API key:

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon",
        "start",
        "<YOUR_NEON_API_KEY>"
      ]
    }
  }
}

Troubleshooting and Windows notes

If you need to run a CLI prompt manually, you can start the server with the following command when prompted by your client configuration tool.

npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>

Security and usage notes

Warning: The Neon MCP Server provides powerful database management capabilities through natural language requests. Always review and authorize actions before execution. It is intended for local development and IDE integrations and is not recommended for production use.

Guides

Explore practical integrations with popular MCP clients to streamline your Neon workflow. Learn how to connect clients, set up safe migrations, and manage projects and databases using natural language prompts.

Notes on development and build

This project uses Bun as the package manager and runtime. Development steps include installing dependencies, building the CLI, and running the local server for testing.

list_projects

Lists the first 10 Neon projects in your account with a summary for each. Increase the limit to see more.

list_shared_projects

Lists Neon projects shared with the current user. Supports search and limit parameters.

describe_project

Fetches detailed information about a specific Neon project, including its ID, name, and associated branches and databases.

create_project

Creates a new Neon project in your Neon account to house branches, databases, roles, and computes.

delete_project

Deletes an existing Neon project and all its associated resources.

list_organizations

Lists all organizations you have access to, with optional filtering by name or ID.

create_branch

Creates a new branch within a Neon project, enabling development, testing, or migrations.

delete_branch

Deletes an existing branch from a Neon project.

describe_branch

Retrieves details about a specific branch, including its name, ID, and parent branch.

list_branch_computes

Lists compute endpoints for a project or specific branch, including details like compute ID, type, size, last active time, and autoscaling.

compare_database_schema

Shows the schema diff between a child branch and its parent.

reset_from_parent

Resets the current branch to its parent’s state, preserving backups if needed.

get_connection_string

Returns your database connection string.

run_sql

Executes a single SQL query against a Neon database.

run_sql_transaction

Executes a series of SQL queries within a single transaction.

get_database_tables

Lists all tables within a specified Neon database.

describe_table_schema

Retrieves the schema of a specific table with columns and constraints.

prepare_database_migration

Initiates a database migration by creating a temporary branch for safe testing.

complete_database_migration

Finalizes the prepared migration by applying changes to the main branch and cleaning up temporary resources.

list_slow_queries

Identifies slow queries using the pg_stat_statements extension.

explain_sql_statement

Provides detailed execution plans for SQL queries to aid optimization.

prepare_query_tuning

Analyzes query performance and suggests optimizations, creating a temporary tuning branch for safe testing.

complete_query_tuning

Finalizes query tuning by applying optimizations or discarding temporary changes.

provision_neon_auth

Sets up Neon Auth for a Neon project to enable authentication integrations.

provision_neon_data_api

Provisions the Neon Data API for HTTP-based access with optional JWT authentication.

search

Searches across organizations, projects, and branches for relevant items and provides links.

fetch

Fetches detailed information about a specific organization, project, or branch by ID.

load_resource

Loads comprehensive Neon documentation and usage guidelines.