Neon MCP Server

Manage Neon serverless Postgres through natural language: run SQL, create branches, perform safe migrations, and tune query performance.

Developer Tools by Neon OAuth2 or API Key (Bearer Token) active

Connect (Remote Server) GitHub Docs npm: @neondatabase/mcp-server-neon

Overview

The Neon MCP Server is an official, open-source server from Neon that lets LLM agents manage Neon serverless Postgres databases through the Model Context Protocol. It acts as a bridge between natural language requests and the Neon API, translating conversational commands into project, branch, and SQL operations. It can be used via Neon's hosted remote server at https://mcp.neon.tech/mcp (OAuth or API key) or run locally from the open-source repo.

The server exposes 30+ tools across project management, branch management, SQL execution, schema migrations, performance tuning, auth provisioning, and documentation search. A standout feature is branch-based migrations: prepare_database_migration applies changes on a temporary branch so they can be tested in isolation, then complete_database_migration promotes them to main. Similar two-step flows exist for query tuning, giving agents a safe path to make schema and performance changes without breaking production.

The server supports read-only mode and tool category scoping via URL query parameters, making it suitable for restricted agent contexts. Neon documents the server as intended for local development and IDE integration, not unattended production use, and emphasizes that humans should review LLM-requested actions before execution.

Tools

Tool	Description
`list_projects`	List Neon projects (default first 10, customizable).
`list_shared_projects`	List shared projects with optional search.
`describe_project`	Retrieve detailed information for a project.
`create_project`	Create a new Neon project.
`delete_project`	Delete a project and its resources.
`list_organizations`	List organizations accessible to the user.
`create_branch`	Create a new branch within a project.
`delete_branch`	Delete an existing branch.
`describe_branch`	Show branch details.
`list_branch_computes`	List compute endpoints attached to a branch.
`compare_database_schema`	Show schema differences between two branches.
`reset_from_parent`	Reset a branch back to its parent state.
`get_connection_string`	Return a Postgres connection string for a branch.
`run_sql`	Execute a single SQL query.
`run_sql_transaction`	Run multiple SQL statements in a transaction.
`get_database_tables`	List tables in a database.
`describe_table_schema`	Show structure of a specific table.
`prepare_database_migration`	Start a migration on a temporary branch for review before applying.
`complete_database_migration`	Apply a prepared migration to the main branch.
`list_slow_queries`	Identify slow queries from pg_stat_statements.
`explain_sql_statement`	Return a Postgres EXPLAIN plan for a query.
`prepare_query_tuning`	Suggest optimizations (indexes, rewrites) for a query.
`complete_query_tuning`	Apply or discard a suggested tuning change.
`provision_neon_auth`	Provision Neon Auth infrastructure for the project.
`provision_neon_data_api`	Enable HTTP-based data API for a project.
`search`	Search across organizations, projects, and branches.
`fetch`	Fetch detailed information for a specific resource.
`list_docs_resources`	List the Neon documentation index.
`get_doc_resource`	Retrieve a specific Neon documentation page.

Setup Guide

Prerequisites

A Neon account: console.neon.tech/signup
Node.js v18.0.0 or higher
An MCP-compatible client (Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed)

Option 1: Quick Setup with neonctl (Recommended)

Auto-detects supported clients (Cursor, VS Code, Claude Code) and handles OAuth + API key creation:

npx neonctl@latest init

Option 2: Remote Server with OAuth

Add via the helper CLI:

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

Or add manually to your MCP client config:

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

Option 3: Remote Server with API Key

Create an API key in the Neon Console, then:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <NEON_API_KEY>"
      }
    }
  }
}

Restricting Capabilities (Optional)

Append query parameters to the URL to scope the server:

?readonly=true for read-only mode (disables writes)
?category=querying&category=schema to restrict to specific tool categories
?projectId=proj-123 to scope all operations to a single project

Example:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=proj-123"
    }
  }
}

Use Cases

Spin up isolated Neon branches per pull request, run migrations against them, and tear them down when the PR closes.
Use prepare_database_migration and complete_database_migration to let an agent draft schema changes on a temporary branch, review the diff, then promote to main.
Investigate production slowness: pull list_slow_queries, run explain_sql_statement on the worst offenders, then iterate with prepare_query_tuning.
Bootstrap a new project: create_project, run schema setup via run_sql_transaction, then provision_neon_auth and provision_neon_data_api.
Give an agent scoped read-only access (?readonly=true&projectId=...) so it can answer ad-hoc data questions without write risk.

Example Prompts

"Create a new Neon project called acme-staging and give me the connection string."
"Create a branch off main called feature/add-orders, add an orders table with id, user_id, and total, and show me the schema diff vs main."
"List my slowest queries in project proj-abc123 and suggest index optimizations for the worst one."
"On a temporary branch, add a created_at timestamp to the users table, then apply the migration to main once it looks good."
"Show me the tables in the production database and describe the schema of the subscriptions table."

Pros

Official, actively maintained by Neon, with both a hosted remote server and a public open-source repo.
Broad coverage: 30+ tools spanning projects, branches, SQL, migrations, performance tuning, and auth.
Safe two-step workflows for migrations and query tuning that use temporary branches before touching main.
Supports read-only mode, tool category restriction, and project scoping via URL query parameters.

Limitations

Documented as intended for local development and IDE integration, not production or unattended agent use.
Self-hosting the open-source server requires several environment variables (OAuth client, cookie secret, Redis KV, token storage Postgres).
Specific to Neon, not a generic Postgres MCP server, so it cannot manage non-Neon databases.

Alternatives

Supabase MCP Server for managing Supabase Postgres projects.
PostgreSQL MCP Server for generic read-only Postgres access against any instance.
Prisma MCP Server for managing Prisma Postgres and running migrations.