Skip to content
MCP Shelf

Neon MCP Server

Neon Postgres from chat: projects, branches, SQL and migrations tested on a branch.

View on GitHub
  • Needs your setup first
  • ★ 658 GitHub stars
  • Last commit 28 Oct 2026

What is Neon MCP Server?

Neon MCP Server is Neon's official hosted server that lets an AI assistant manage Neon Postgres projects, branches and computes, run SQL, and test schema migrations on a temporary branch.

Tools
65
Runs on
Hosted
Licence
MIT
GitHub stars
658

Good for

  • Spinning up a Postgres database for a prototype straight from the editor
  • Trying a schema change on a branch before applying it to the main one
  • Finding slow queries and testing an index on a copy of the data

You'll need

  • A Neon account (OAuth sign-in) or a Neon API key
  • A client that connects to a remote server by URL, or Node.js 18 or newer for npx mcp-remote
Works withClaude CodeCursorClaude DesktopVS CodeCodexWindsurfChatGPTEach has a ready-made config on the Install tab, built from the README.

Needs your setup firstIt needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 10 Nov 2026 we read its tools from the source code instead of running this config. The shared database listed "npx neonctl". The local @neondatabase/mcp-server-neon package is deprecated; Neon now runs the server at mcp.neon.tech, so this page uses that address.

Try asking Neon MCP Server

Once it is installed, ask your assistant things like:

  • Create a branch of my database and test this migration on it.
  • Compare the schema of the dev branch with main.
  • List my Neon projects and their branches.

MCP Shelf take

Neon needs something our Linux test machine does not have (an account, an app or a service), so on 10 Nov 2026 we read its source and counted 65 tools. 33 of the 65 only read; the other 32 can change things. It sits 9th of 10 in its category on our shelf by GitHub stars (658).
MCP Shelf tests: numbers from our own runs, not the README · tested on 10 Nov 2026

What can Neon MCP Server read and change?

It can read

  • Your Neon organisations, projects, branches, computes and usage
  • Schemas, tables and any rows the role can read, through SQL

It can change

  • Projects, branches, computes, roles and databases, including deletes
  • Data and schema, through run_sql and migrations
  • Neon Auth, Data API and functions settings, if those groups are loaded

Safer setup: Use readonly=true, or untick Allow writes on the sign-in page, and add projectId and a low-privilege roleName. Neon says the server is for development, not production, and that you should review each action before it runs.

Neon MCP Server in more detail

Neon hosts this server at mcp.neon.tech and signs you in with OAuth, so there is nothing to install. Through it an assistant can create and describe projects, make and reset branches, start or suspend computes, read table schemas and run SQL. Its migration and query-tuning tools work on a temporary branch first and only touch your real branch when you say so.

The full server publishes about 140 tools across Neon Auth, the Data API, functions, storage and logs, which is a lot for a model to carry. Neon's README suggests a URL that loads only projects, branches, computes, querying and schema, and that is the one on this page. Add readonly=true to the URL, or untick Allow writes when you sign in, for a version that can only look.

Made by
Neon (neondatabase/mcp-server-neon)
Last commit
28 Oct 2026
Setup checked
10 Nov 2026
Page updated
10 Nov 2026

What's in the pod

What tools does Neon MCP Server have?

We found 65 tools in its source code on 10 Nov 2026. 33 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

How we tested it: Read from Neon's public tool list (mcp.neon.tech/api/list-tools) for the five categories in this page's URL. The server itself needs a Neon sign-in. Read-only here means the tool stays available with readonly=true.

Runs commands2 tools · Can start programs or run code.

ToolWhat it is for
run_sqlRuns one SQL statement on a branch and returns the rows. Inside a READ ONLY transaction in read-only mode.
run_sql_transactionRuns several statements in one transaction. Not available in read-only mode.

Changes things30 tools · Can create, edit, send or delete.

ToolWhat it is for
complete_database_migrationApplies a tested migration to the real branch, or discards it, and deletes the temporary one.
complete_query_tuningApplies or discards those tuning changes and deletes the temporary branch.
create_branchMakes a branch from its parent's current data, with its own compute.
create_postgres_roleCreates a Postgres role and returns its password. By default it is an admin; pass read_only or read_write for least privilege.
create_projectCreates a project with a default branch and compute and waits until it is ready.
delete_projectDeletes a project and everything in it. Its description tells the model to ask you first, and recover_project undoes it within 7 days.
get_connection_stringReturns a Postgres connection string with a password. Withheld in read-only mode.
prepare_database_migrationApplies a schema change on a new temporary branch so it can be tested there.
prepare_query_tuningRuns EXPLAIN ANALYZE for a slow query on a temporary branch and suggests changes.
reset_from_parentThrows away a branch's own changes and resets it to its parent.
start_postgres_endpointWakes a suspended compute.
suspend_postgres_endpointSuspends a compute and drops its connections.
  • create_credential
  • create_postgres_database
  • create_postgres_endpoint
  • delete_branch
  • delete_postgres_database
  • delete_postgres_endpoint
  • delete_postgres_role
  • finalize_branch_restore
  • recover_project
  • reset_postgres_role_password
  • restart_postgres_endpoint
  • revoke_credential
  • rotate_credential
  • set_default_branch
  • update_branch
  • update_postgres_database
  • update_postgres_endpoint
  • update_project

Only reads33 tools · Looks things up and changes nothing.

ToolWhat it is for
compare_database_schemaDiffs a database's schema on one branch against another, by default its parent.
describe_branchSummarises a branch: its databases and a tree of schemas, tables and views.
describe_projectShows a project's settings, owner and usage.
describe_table_schemaShows a table's columns, indexes, constraints and size.
explain_sql_statementReturns a query plan as JSON; with analyze it actually runs the statement.
fetchReturns one of those by the id search gave.
get_database_tablesLists the tables and views outside the system schemas.
inspect_databaseRuns one read-only neon inspect check, such as outliers, which ranks queries by total time, or the cache hit rate.
list_branchesLists a project's branches with their parent and which is the default.
list_incidentsLists open Neon incidents and maintenance from the status page.
list_projectsLists the projects in an organisation, with a name or id search.
list_slow_queriesLists queries from pg_stat_statements, slowest first.
searchFinds organisations, projects, branches, computes and snapshots by name or id.
  • count_projects
  • get_branch
  • get_branch_consumption
  • get_default_branch
  • get_operation
  • get_postgres_database
  • get_postgres_endpoint
  • get_postgres_role
  • get_project_consumption
  • list_branch_computes
  • list_credentials
  • list_operations
  • list_organizations
  • list_postgres_databases
  • list_postgres_endpoints
  • list_postgres_roles
  • list_project_members
  • list_project_permissions
  • list_regions
  • send_feedback

Tool groups

projects
Organisations, projects, regions, operations, permissions and consumption. In the URL on this page.
branches
Branches, resets and restores, Postgres roles and databases, connection strings. In the URL on this page.
endpoints
Compute endpoints: create, resize, start, suspend and restart. In the URL on this page.
querying
run_sql, transactions, EXPLAIN, slow queries, health checks, and the migration and query-tuning flows. In the URL on this page.
schema
Tables, table schemas and schema diffs between branches. In the URL on this page.
snapshots, neon_auth, data_api, functions, storage, realtime, observability, docs
The rest of Neon: snapshots and schedules, Neon Auth users and providers, the Data API, functions, storage, realtime, logs, and Neon docs search. Add a category parameter for each, or drop the parameters for all of them.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

How do I install Neon MCP Server?

Quick install

One command from the README sets it up for you:

Terminal
npx neon@latest init

Or paste it into your app by hand:

Where it goes: Your terminal, in the project folder

Claude Code
claude mcp add --transport http neon 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema'
Codex, Windsurf, ChatGPT and more →

Install steps from the Neon MCP Server README

The project's own instructions, copied from its README on GitHub on 16 Nov 2026 under its MIT licence. They are the source of truth; the ready-made configs further down are built from them. The full README is on GitHub.

Prerequisites
  • An MCP Client application.
  • A Neon account.
  • Node.js (>= v18.0.0): Download from nodejs.org.
  • If IP Allow is enabled, add 34.192.103.46 and 23.22.233.166 to your allowlist (mcp.neon.tech static IPs).

For development, you'll need Node.js 22+ (pnpm is provided via Corepack — run corepack enable to activate it).

Option 1. Quick Setup with API Key

Don't want to manually create an API key?

Run neon@latest init to automatically configure Neon's MCP Server with one command:

npx neon@latest init

This works with Cursor, VS Code (GitHub Copilot), and Claude Code. It will authenticate via OAuth, create a Neon API key for you, and configure your editor automatically.

Option 2. Remote Hosted MCP Server (OAuth Based Authentication)

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.

Run the following command to add the Neon MCP Server for all detected agents and editors in your workspace:

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

That URL publishes projects, branches, compute endpoints, querying, and schema. Preview it with /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. The unfiltered URL publishes every category:

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

Add the -g flag to add the Neon MCP Server to the global MCP server list instead of project-scoped.

Alternatively, you can add the following "Neon" entry to your client's MCP server configuration file (e.g., 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: Add the following to your Kiro MCP config file (~/.kiro/settings/mcp.json for global, or .kiro/settings/mcp.json for project-scoped):

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

Or use the "Add to Kiro" button at the top of this README to install the Neon Kiro Power, which includes the Neon MCP Server. For more information, see the Kiro MCP documentation.

  • Restart or refresh your MCP client.
  • An OAuth window will open in your browser. Follow the prompts to authorize your MCP client to access your Neon account.

With OAuth-based authentication, the MCP server will, by default, operate on projects under your personal Neon account. To access or manage projects that belong to an organization, you must explicitly provide either the org_id or the project_id in your prompt to MCP client.

Option 3. Remote Hosted MCP Server (API Key Based Authentication)

Remote MCP Server also supports authentication using an API key in the Authorization header if your client supports it.

Create a Neon API key in the Neon Console. Next, run the following command to add the Neon MCP Server for all detected agents and editors in your workspace:

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

Alternatively, you can add the following "Neon" entry to your client's MCP server configuration file (e.g., 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>"
      }
    }
  }
}

Provide an organization's API key to limit access to projects under the organization only.

Scopes and Read-Only Mode

Neon MCP advertises OAuth scopes read and write. Your MCP client can request these, or you can make the selection in the OAuth permissions UI. * is treated as write if a client still sends it.

Read-only mode restricts which tools are available, disabling write operations like creating projects, branches, or running migrations. Read-only tools include listing projects, describing schemas, querying data, and viewing performance metrics.

You can set read-only mode in two ways:

  1. Default MCP URL (editable consent): Connect with https://mcp.neon.tech/mcp and uncheck Allow writes on the authorization page. You can also choose one project, a Postgres role for SQL, and a subset of tool categories there.
  2. Parameterized MCP URL (fixed consent): Put readonly, projectId, category, and/or roleName on the MCP server URL. The authorization page confirms that grant and does not offer editors. Change the URL and authorize again to change the grant.
{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

How the query param behaves:

  • API key flow: readonly=true is the way to enable read-only mode (there is no OAuth scope exchange in this flow). URL changes apply on the next request.
  • OAuth flow: projectId, category, readonly, and roleName on the MCP URL are a fixed grant confirmed at authorization. readonly=true cannot be widened to writes on that page. After a token is issued, changing the URL does not widen that token; authorize again.

For OAuth registration, x-read-only is an initial Allow-writes default on editable consent. It does not lock confirmation, and it does not reduce a parameterized URL that includes readonly=false. API-key requests still honor x-read-only per request, below the readonly query param.

Note: Read-only mode restricts which tools are available. run_sql stays available and runs each query in a READ ONLY transaction. run_sql_transaction is not available; run each statement with run_sql. Those calls run separately and do not share a transaction. For transaction semantics, use a connection with writes allowed.

Transport compatibility

https://mcp.neon.tech/mcp uses stateless Streamable HTTP. It supports the MCP 2026-07-28 protocol and a stateless fallback for 2025-era clients. The deprecated HTTP+SSE /sse and /message endpoints return 410 Gone.

Connect Streamable HTTP clients to https://mcp.neon.tech/mcp. For clients that only support local stdio servers, put this in the client config so mcp-remote bridges to Streamable HTTP:

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

A request with a malformed Origin header receives 403 Forbidden. Any serialized origin is accepted, including web pages, browser extensions, desktop webviews and null, so browser-based clients can connect. Requests without an Origin are unaffected.

What you need first

  • A Neon account (OAuth sign-in) or a Neon API key
  • A client that connects to a remote server by URL, or Node.js 18 or newer for npx mcp-remote

Add Neon MCP Server to your app

Pick your app for a ready-to-paste snippet and where it goes, built from the steps above.

Where it goes: Your terminal, in the project folder

Claude Code
claude mcp add --transport http neon 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema'

Your client opens a browser window to sign in to Neon. For a client without OAuth, add an Authorization: Bearer header with a Neon API key. Drop the category parameters to load every tool group.

Remote option

The same server limited to tools that only read. run_sql still works, but each query runs inside a READ ONLY transaction.

Server URL
https://mcp.neon.tech/mcp?readonly=true

Checked against the project's own install docs on 10 Nov 2026: neondatabase/mcp-server-neon README, neon.com/docs/ai/neon-mcp-server, mcp.neon.tech/api/list-tools.

Did this work for you?

Projects change their install steps often. If Neon MCP Server did not install, or something here no longer matches the project, tell us and we will check it against the README and fix the page.

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop, VS Code, Codex and ChatGPT. If it will not start, test it in MCP Inspector and look up the error in Fixing MCP server errors.

Neon MCP Server not working? Common fixes

The /sse address returns 410 Gone
Neon retired the old SSE endpoint. Use https://mcp.neon.tech/mcp, or npx -y mcp-remote with that URL for clients that only run local commands.
It cannot see projects in my company's organisation
With OAuth it defaults to your personal account. Name the organisation or project id in your prompt, or connect with an organisation API key.
Connections fail with IP Allow turned on
Add Neon MCP's static addresses, 34.192.103.46 and 23.22.233.166, to the project's allowlist.
The model is slow or picks the wrong tool
The full server has about 140 tools. Load only the groups you need with category parameters, as the URL on this page does.
get_connection_string is missing
It is withheld in read-only mode and with a pinned roleName, because the string carries a privileged password. Copy it from the Neon Console instead.

How do I configure Neon MCP Server?

Names are exactly as the project spells them. Required ones are marked.

SettingWhat it does
readonlyConfigURL parameter that limits the server to tools that only read. With an API key it is the only way to get read-only mode.https://mcp.neon.tech/mcp?readonly=true
categoryConfigURL parameter, repeated or comma-separated, that loads only the named tool groups.?category=querying&category=schema
projectIdConfigURL parameter that keeps every call inside one Neon project.?projectId=proj-123
roleNameConfigURL parameter that runs all SQL as that Postgres role instead of the database owner, so Postgres grants decide what the agent can touch.?roleName=app_reader
Authorization: BearerConfigHeader carrying a Neon API key, for clients that cannot sign in with OAuth. An organisation's key limits it to that organisation's projects.Authorization: Bearer YOUR_NEON_API_KEY

Neon MCP Server FAQ

Is the Neon MCP Server official?

Yes. Neon builds it in the neondatabase organisation on GitHub under the MIT licence and runs it at mcp.neon.tech.

How do I set up the Neon MCP Server in Cursor or Claude Code?

Run npx neon@latest init, which signs you in and configures Cursor, VS Code or Claude Code for you. By hand, add https://mcp.neon.tech/mcp as a remote server and sign in with OAuth when the client asks.

Can I make it read-only?

Yes. Add readonly=true to the URL, or untick Allow writes on the sign-in page. Write tools disappear, and run_sql runs each query in a READ ONLY transaction.

Is it safe to use on a production database?

Neon says no: it is meant for local development and IDE work. If you point it at real data, combine readonly, projectId and a roleName with only SELECT grants, and approve each action yourself.

How do migrations work?

prepare_database_migration applies the change on a temporary branch, so you can test it there. complete_database_migration then applies it to your branch or throws it away, and deletes the temporary one.

Why does the URL on this page have category parameters?

The full server publishes about 140 tools, which crowds a model's context. Neon's README suggests loading projects, branches, endpoints, querying and schema, which covers everyday work with about 65 tools.

Do I need an API key?

Not with OAuth, which most clients support. Use a Neon API key in an Authorization: Bearer header for agents that cannot open a browser to sign in.

What does it cost?

The server is free. Neon bills for the Postgres compute and storage you use, and its free plan covers small projects.

Can I use Neon MCP Server in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named neon with type http and the URL https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema. Then switch Copilot Chat to Agent mode to use its tools.

Does Neon MCP Server work with Codex?

Yes. Run codex mcp add neon --url 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema' in a terminal, or add an [mcp_servers.neon] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share. Then codex mcp login neon if it asks you to sign in.

Two peas, one chat

Chat with AI about Neon

Opens a chat primed with Neon’s README and setup docs from this page, or add it in Cursor to use its tools.

The Cursor button opens Cursor and asks before it adds the server. Fill in any keys it needs in Cursor’s MCP settings.

Peas in a pod

What are the alternatives to Neon MCP Server?

How Neon MCP Server lines up against its neighbours on the shelf. See every databases and data server.

  • Neon MCP ServerThis pea

    Neon Postgres from chat: projects, branches, SQL and migrations tested on a branch.

    Tools
    65
    Runs on
    Hosted
    Licence
    MIT
    Stars
    658
  • Redis MCP Server

    Redis's own server: keys, hashes, streams, JSON and vector search in plain English.

    Tools
    53
    Runs on
    Your computer
    Licence
    MIT
    Stars
    641
  • Postgres MCP Pro

    SQL, query plans, health checks and index advice for Postgres.

    Tools
    9
    Runs on
    Your computer
    Licence
    MIT
    Stars
    3.4K
  • Supabase

    Manage Supabase projects, tables, migrations, logs and Edge Functions.

    Tools
    29
    Runs on
    Hosted
    Licence
    Apache-2.0
    Stars
    3K
  • MCP Toolbox for Databases

    Google's toolbox for Postgres, MySQL, BigQuery, Spanner and other databases.

    Tools
    29
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    16.7K
  • Qdrant

    Store notes and find them by meaning in a Qdrant vector collection.

    Tools
    2
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    1.6K

Recommended as an alternative to Supabase MCP.

Full docs on GitHubneondatabase/mcp-server-neon

Something wrong on this page? Tell us.

For bots & AI agents

Machine-readable versions of Neon MCP Server and MCP Shelf. Fetch these instead of parsing this page.

This listing (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs