The Neon MCP Server is an open-source tool that lets you interact with your Neon Postgres databases in natural language:
- Manage projects, branches, and databases with conversational commands
- Run SQL queries and make schema changes without writing code
- Use branch-based migrations for safer schema modifications
Quick setup
The fastest way to set up Neon's MCP Server is with one command:
npx neonctl@latest initThis configures the Neon MCP Server for compatible MCP clients in your workspace (Cursor, VS Code, Claude Code, and others) using API key authentication. See the neonctl init documentation.
If you only want the MCP server and nothing else, use:
npx add-mcp https://mcp.neon.tech/mcpThis command adds the required configuration to your editor's MCP config files; it does not open a browser by itself. Add -g for global (user-level) setup instead of project-level. Restart your editor (or enable the MCP server in your editor's settings). When you use the MCP connection, an OAuth window will open in your browser to authorize access to your Neon account. For more options (e.g., global vs project-level), see the add-mcp repository.
Other setup options:
- API key authentication (remote agents): For remote agents or when OAuth isn't available:
npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer $NEON_API_KEY" - Manual configuration: See Connect MCP clients for step-by-step instructions for any editor, including Windsurf, ChatGPT, Zed, and others.
After setup, restart your editor and ask your AI assistant to "Get started with Neon" to launch the interactive onboarding guide.
Imagine you want to create a new database. Instead of using the Neon Console or API, you could just type a request like, "Create a database named 'my-new-database'". Or, to see your projects, you might ask, "List all my Neon projects". The Neon MCP Server makes this possible.
It works by acting as a bridge between natural language requests and the Neon API. Built upon the Model Context Protocol (MCP), it translates your requests into the necessary Neon API calls, allowing you to manage everything from creating projects and branches to running queries and performing database migrations.
Neon MCP Server Security Considerations
The Neon MCP Server grants powerful database management capabilities through natural language requests. Always review and authorize actions requested by the LLM before execution. Ensure that only authorized users and applications have access to the Neon MCP Server.
Other setup options
Connect to Neon's managed MCP server using OAuth. No API key configuration needed.
npx add-mcp https://mcp.neon.tech/mcpOr add this to your MCP config file:
{
"mcpServers": {
"neon": {
"type": "http",
"url": "https://mcp.neon.tech/mcp"
}
}
}One-click install for Cursor
After saving, restart your MCP client. When the OAuth window opens in your browser, review the requested permissions and click Authorize to complete the connection.
Read-only mode
The Neon MCP Server supports read-only mode for safe operation. Enable it by adding the x-read-only: true header:
{
"mcpServers": {
"neon": {
"type": "http",
"url": "https://mcp.neon.tech/mcp",
"headers": {
"x-read-only": "true"
}
}
}
}When enabled, the server restricts all operations to read-only tools and SQL queries automatically run in read-only transactions. This provides a safe method for querying and analyzing databases without risk of accidental modifications.
Troubleshooting
If your client does not use JSON for configuration of MCP servers (such as older versions of Cursor), use this command when prompted:
npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>note
For clients that don't support Streamable HTTP, you can use the deprecated SSE endpoint: https://mcp.neon.tech/sse. SSE is not supported with API key authentication.
Security Considerations
The Neon MCP Server grants powerful database management capabilities through natural language requests. Always review and authorize actions requested by the LLM before execution. The Neon MCP Server is intended for local development and IDE integrations only. For more information, see MCP security guidance.
Supported actions (tools)
The Neon MCP Server provides the following actions, which are exposed as "tools" to MCP clients. You can use these tools to interact with your Neon projects and databases using natural language commands.
Project management:
list_projects: Lists the first 10 Neon projects in your account, providing a summary of each project. If you can't find a specific project, increase the limit by passing a higher value to the limit parameter.list_shared_projects: Lists Neon projects shared with the current user. Supports a search parameter and limiting the number of projects returned (default: 10).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. A project acts as a container for branches, databases, roles, and computes.delete_project: Deletes an existing Neon project and all its associated resources.list_organizations: Lists all organizations that the current user has access to. Optionally filter by organization name or ID using the search parameter.
Branch management:
create_branch: Creates a new branch within a specified Neon project. Leverages Neon's branching feature for development, testing, or migrations.delete_branch: Deletes an existing branch from a Neon project.describe_branch: Retrieves details about a specific branch, such as its name, ID, and parent branch.list_branch_computes: Lists compute endpoints for a project or specific branch, including compute ID, type, size, last active time, and autoscaling information.compare_database_schema: Shows the schema diff between the child branch and its parent.reset_from_parent: Resets the current branch to its parent's state, discarding local changes. Automatically preserves to backup if branch has children, or optionally preserve on request with a custom name.
SQL query execution:
get_connection_string: Returns your database connection string.run_sql: Executes a single SQL query against a specified Neon database. Supports both read and write operations.run_sql_transaction: Executes a series of SQL queries within a single transaction against a Neon database.get_database_tables: Lists all tables within a specified Neon database.describe_table_schema: Retrieves the schema definition of a specific table, detailing columns, data types, and constraints.
Database migrations (schema changes):
prepare_database_migration: Initiates a database migration process. Critically, it creates a temporary branch to apply and test the migration safely before affecting the main branch.complete_database_migration: Finalizes and applies a prepared database migration to the main branch. This action merges changes from the temporary migration branch and cleans up temporary resources.
Query performance optimization:
list_slow_queries: Identifies performance bottlenecks by finding the slowest queries in a database. Requires the pg_stat_statements extension.explain_sql_statement: Provides detailed execution plans for SQL queries to help identify performance bottlenecks.prepare_query_tuning: Analyzes query performance and suggests optimizations, like index creation. Creates a temporary branch for safely testing these optimizations.complete_query_tuning: Finalizes query tuning by either applying optimizations to the main branch or discarding them. Cleans up the temporary tuning branch.
Neon Auth:
provision_neon_auth: Provisions Neon Auth for a Neon project. It allows developers to easily set up authentication infrastructure by creating an integration with an Auth provider.
Neon Data API:
provision_neon_data_api: Provisions the Neon Data API for a branch, enabling HTTP-based Data API access with optional JWT authentication.
Search and discovery:
search: Searches across organizations, projects, and branches matching a query. Returns IDs, titles, and direct links to the Neon Console.fetch: Fetches detailed information about a specific organization, project, or branch using an ID (typically from the search tool).
Documentation and resources:
load_resource: Loads comprehensive Neon documentation and usage guidelines, including the "neon-get-started" guide for setup, configuration, and best practices.
Usage examples
After setup, interact with your Neon databases using natural language:
"Get started with Neon"— Launch the interactive onboarding guide"List my Neon projects""Create a project named 'my-app'""Show tables in database 'main'""Search for 'production' across my Neon resources""SELECT * FROM users LIMIT 10"
MCP security guidance
The Neon MCP server provides powerful database tools. We recommend MCP for development and testing only, not production environments.
- Use MCP only for local development or IDE-based workflows
- Never connect MCP agents to production databases
- Avoid exposing production or PII data—use anonymized data only
- Always review and authorize LLM-requested actions before execution
- Restrict MCP access to trusted users and regularly audit access
Resources
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.