neondatabase/mcp-server-neon

Neon MCP Server – A natural‑language bridge to Neon Postgres

What it is

• An open‑source MCP (Model Context Protocol) server that sits between a large language model (LLM) and the Neon serverless Postgres platform.
• It receives natural‑language requests from an LLM‑enabled client (Claude Code, Cursor, VS Code, Kiro, etc.), translates them into Neon API calls, and returns the result.

Why it matters

• Lets non‑technical users manage databases—create projects/branches, run queries, apply migrations—without writing SQL or memorising Neon’s REST endpoints.
• Demonstrates a concrete use‑case of the Model Context Protocol, a standard for safely passing context (auth, intent, parameters) between LLMs and external services.

Key capabilities

Capability	How it works	Example command
Project & branch lifecycle	Calls Neon Management API (create_project, list_branches, delete_branch, …)	“Create a new Postgres database called my‑database and add a users table.”
Schema inspection & migration	Uses Neon schema tools (describe_table_schema, prepare_database_migration, complete_database_migration)	“Add a created_at column to the users table.”
Query execution	Runs run_sql (read‑only) or run_sql_transaction (write) against a branch’s compute endpoint	“Show me the first 10 rows of users.”
Observability & docs	Exposes read‑only tools like list_slow_queries, inspect_database, search for docs/resources	“Give me a summary of all my Neon projects.”

How you use it

1. Quick‑setup – run npx neon@latest init. The script creates an API key, registers the MCP server with your editor, and opens the OAuth consent screen.
2. Remote hosted server – add the public MCP endpoint (https://mcp.neon.tech/mcp) to your client’s mcp.json (or use the one‑click Kiro button). Authentication can be OAuth (preferred) or an API‑key header.
3. Fine‑grained access – control what the LLM can do via URL query parameters:
   • readonly=true – only read‑only tools are exposed.
   • category=… – limit to specific tool groups (e.g., querying and schema).
   • projectId=… – lock all actions to a single Neon project.

Security notes

• The server can perform powerful actions (create/delete projects, run migrations). Always review the LLM‑generated plan before the server executes it.
• Intended for local development / IDE integration; the docs advise against using it in production.
• If your Neon account uses IP‑allow lists, add the static IPs 34.192.103.46 and 23.22.233.166.

Architecture snapshot

• Deployed as a Next.js App Router app on Vercel (mcp.neon.tech).
• Core folders:
  • app/api/[transport]/route.ts – handles the two transport modes (Streamable HTTP default and deprecated SSE).
  • app/api/authorize/* – OAuth flow (discover, token, revoke).
  • mcp/ – definitions of all “tools”, request handlers, analytics, Sentry integration.
  • lib/ – helpers for OAuth, config, error handling.

Where to learn more

• Official docs: https://neon.com/docs/ai/neon-mcp-server
• Guides for specific editors/agents (Cursor, Claude Code, Cline, Windsurf, Zed, etc.) linked in the README.

Bottom line Neon MCP Server is a real, production‑grade bridge that lets LLM‑powered assistants manage serverless Postgres databases through natural language, while giving developers fine‑grained control over permissions and scope via the Model Context Protocol.