
Neon MCP Server
Neon Postgres from chat: projects, branches, SQL and migrations tested on a branch.
- 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
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).
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.
| Tool | What it is for |
|---|---|
run_sql | Runs one SQL statement on a branch and returns the rows. Inside a READ ONLY transaction in read-only mode. |
run_sql_transaction | Runs several statements in one transaction. Not available in read-only mode. |
Changes things30 tools · Can create, edit, send or delete.
| Tool | What it is for |
|---|---|
complete_database_migration | Applies a tested migration to the real branch, or discards it, and deletes the temporary one. |
complete_query_tuning | Applies or discards those tuning changes and deletes the temporary branch. |
create_branch | Makes a branch from its parent's current data, with its own compute. |
create_postgres_role | Creates a Postgres role and returns its password. By default it is an admin; pass read_only or read_write for least privilege. |
create_project | Creates a project with a default branch and compute and waits until it is ready. |
delete_project | Deletes 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_string | Returns a Postgres connection string with a password. Withheld in read-only mode. |
prepare_database_migration | Applies a schema change on a new temporary branch so it can be tested there. |
prepare_query_tuning | Runs EXPLAIN ANALYZE for a slow query on a temporary branch and suggests changes. |
reset_from_parent | Throws away a branch's own changes and resets it to its parent. |
start_postgres_endpoint | Wakes a suspended compute. |
suspend_postgres_endpoint | Suspends a compute and drops its connections. |
create_credentialcreate_postgres_databasecreate_postgres_endpointdelete_branchdelete_postgres_databasedelete_postgres_endpointdelete_postgres_rolefinalize_branch_restorerecover_projectreset_postgres_role_passwordrestart_postgres_endpointrevoke_credentialrotate_credentialset_default_branchupdate_branchupdate_postgres_databaseupdate_postgres_endpointupdate_project
Only reads33 tools · Looks things up and changes nothing.
| Tool | What it is for |
|---|---|
compare_database_schema | Diffs a database's schema on one branch against another, by default its parent. |
describe_branch | Summarises a branch: its databases and a tree of schemas, tables and views. |
describe_project | Shows a project's settings, owner and usage. |
describe_table_schema | Shows a table's columns, indexes, constraints and size. |
explain_sql_statement | Returns a query plan as JSON; with analyze it actually runs the statement. |
fetch | Returns one of those by the id search gave. |
get_database_tables | Lists the tables and views outside the system schemas. |
inspect_database | Runs one read-only neon inspect check, such as outliers, which ranks queries by total time, or the cache hit rate. |
list_branches | Lists a project's branches with their parent and which is the default. |
list_incidents | Lists open Neon incidents and maintenance from the status page. |
list_projects | Lists the projects in an organisation, with a name or id search. |
list_slow_queries | Lists queries from pg_stat_statements, slowest first. |
search | Finds organisations, projects, branches, computes and snapshots by name or id. |
count_projectsget_branchget_branch_consumptionget_default_branchget_operationget_postgres_databaseget_postgres_endpointget_postgres_roleget_project_consumptionlist_branch_computeslist_credentialslist_operationslist_organizationslist_postgres_databaseslist_postgres_endpointslist_postgres_roleslist_project_memberslist_project_permissionslist_regionssend_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:
npx neon@latest initOr paste it into your app by hand:
Where it goes: Your terminal, in the project folder
claude mcp add --transport http neon 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema'Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
"mcpServers": {
"neon": {
"url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
}
}
}Where it goes: Customize → Connectors → add a custom connector
https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schemaPaste the URL as a custom connector and sign in to Neon in the window that opens. If your plan has no custom connectors, use npx -y mcp-remote with the same URL in the config file.
Where it goes: .vscode/mcp.json in your project
{
"servers": {
"neon": {
"type": "http",
"url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
}
}
}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.46and23.22.233.166to your allowlist (mcp.neon.techstatic 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_idor theproject_idin 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:
- Default MCP URL (editable consent): Connect with
https://mcp.neon.tech/mcpand 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. - Parameterized MCP URL (fixed consent): Put
readonly,projectId,category, and/orroleNameon 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=trueis 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, androleNameon the MCP URL are a fixed grant confirmed at authorization.readonly=truecannot 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_sqlstays available and runs each query in aREAD ONLYtransaction.run_sql_transactionis not available; run each statement withrun_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 mcp add --transport http neon 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema'Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
"mcpServers": {
"neon": {
"url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
}
}
}Where it goes: Customize → Connectors → add a custom connector
https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schemaPaste the URL as a custom connector and sign in to Neon in the window that opens. If your plan has no custom connectors, use npx -y mcp-remote with the same URL in the config file.
Where it goes: .vscode/mcp.json in your project
{
"servers": {
"neon": {
"type": "http",
"url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
}
}
}Where it goes: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app
[mcp_servers.neon]
url = "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"Or run: codex mcp add neon --url 'https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema', then codex mcp login neon if it asks you to sign in.
Where it goes: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"neon": {
"serverUrl": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
}
}
}Where it goes: chatgpt.com/plugins → + → Add custom MCP server
https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schemaPaste the URL as the server address, choose OAuth if it asks you to sign in, create it as a plugin, then install it before using it in a chat. Workspace admins can block custom servers.
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.
https://mcp.neon.tech/mcp?readonly=trueChecked 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.
| Setting | What it does |
|---|---|
readonlyConfig | URL 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 |
categoryConfig | URL parameter, repeated or comma-separated, that loads only the named tool groups.?category=querying&category=schema |
projectIdConfig | URL parameter that keeps every call inside one Neon project.?projectId=proj-123 |
roleNameConfig | URL 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: BearerConfig | Header 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's own server: keys, hashes, streams, JSON and vector search in plain English.
- Tools
- 53
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 641

SQL, query plans, health checks and index advice for Postgres.
- Tools
- 9
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 3.4K

Manage Supabase projects, tables, migrations, logs and Edge Functions.
- Tools
- 29
- Runs on
- Hosted
- Licence
- Apache-2.0
- Stars
- 3K
Google's toolbox for Postgres, MySQL, BigQuery, Spanner and other databases.
- Tools
- 29
- Runs on
- Your computer
- Licence
- Apache-2.0
- Stars
- 16.7K
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.
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