AI-assisted database migrations with Cursor and Neon Postgres MCP Server

Imagine adjusting your database schema simply by describing the change in plain English. This is possible by combining Cursor with the Neon MCP Server.

This guide demonstrates how to use Cursor's Composer and Neon's MCP server to perform database migrations in your Neon project.

Key components

Let's break down the key components in this setup:

• Cursor: Cursor is an AI-first code editor that supports Model Context Protocol (MCP) for interfacing with external tools (APIs, databases, etc.)

• Neon MCP Server: Neon's MCP server acts as a bridge between MCP clients like Cursor and Neon's API, letting you work with Neon databases using natural language commands.

• Model Context Protocol (MCP): MCP is a lightweight communication standard that allows Cursor and Neon MCP Server to work together.

Setting up Neon MCP Server in Cursor

The following steps show how to set up Neon MCP Server in Cursor.

Prerequisites

Before you begin, ensure you have the following:

1. Cursor Editor: Download and install Cursor from cursor.com.

2. A Neon Account and Project: You'll need a Neon account and a project. You can quickly create a new Neon project here pg.new

3. Neon API Key: After signing up, get your Neon API Key from the Neon console. This API key is needed to authenticate your application with Neon. For instructions, see Manage API keys.

   Neon API Key Security

   Keep your Neon API key secure, and never share it publicly. It provides access to your Neon projects.

4. Node.js (>= v18) and npm: Ensure Node.js (version 18 or later) and npm are installed. Download them from nodejs.org.

Installation and Configuration

Add Neon MCP Server to Cursor:

1. Open Cursor and go to Cursor Settings in the Navbar.

2. In Settings, navigate to Features.

3. Scroll to the MCP Servers section.

4. Click + Add new MCP server.

5. In the "Add MCP Server" modal:

   • Name: Give your server a descriptive name (e.g., Neon).

   • Type: Select command.

   • Command: Enter the following command, replacing <YOUR_NEON_API_KEY> with your actual Neon API key which you obtained earlier in the Prerequisites section.

     npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>

   • Click Add.

     

   Cursor will attempt to connect. Your new "Neon" MCP server should appear in the MCP Servers list with all the available tools.

   

You've now configured Neon MCP Server in Cursor and can manage your Neon Postgres databases using AI.

Neon MCP Server Tools

Neon MCP server exposes the following actions, which primarily map to Neon API endpoints:

• list_projects: Lists all your Neon projects. This uses the Neon API to retrieve a summary of all projects associated with your Neon account. Note: This particular action is still under development. It's not yet returning results as expected.
• describe_project: Retrieves detailed information about a specific Neon project. Provides comprehensive details about a chosen project, such as its ID, name, and associated branches.
• create_project: Creates a new Neon project — a container in Neon for branches, databases, roles, and computes.
• delete_project: Deletes an existing Neon project.
• create_branch: Creates a new branch within a Neon project. Leverages Neon's branching feature, allowing you to create new branches for development or migrations.
• delete_branch: Deletes an existing branch in a Neon project.
• describe_branch: Retrieves details about a specific branch. Retrieves information about a particular branch, such as its name and ID.
• run_sql: Runs a single SQL query against a Neon database. Allows you to run read or write SQL queries.
• run_sql_transaction: Runs a series of SQL queries within a transaction against a Neon database. Enables running multiple SQL statements as a single atomic transaction, ensuring data consistency.
• get_database_tables: Lists all tables in a specified Neon database. Provides a list of tables.
• describe_table_schema: Retrieves the schema definition of a specific table. Details the structure of a table, including columns and data types.
• prepare_database_migration: Initiates a database migration process, utilizing a temporary branch for safety. Begins the process of altering your database schema, safely using Neon's branching feature.
• complete_database_migration: Completes a migration process, applying changes to your main database and cleaning up temporary resources.

These actions enable any MCP client like Cursor to interact with various functionalities of the Neon platform via the Neon API. Certain tools, especially database migration ones, are tailored for AI agent and LLM usage, leveraging Neon’s branching for safe preview and commit.

Development Workflow: Adding a Column with Cursor and Neon MCP

Let's walk through a typical development scenario: Quickly adding a column for prototyping using natural language within Cursor. The following chat log demonstrates a real interaction with Cursor and the Neon MCP server.

Scenario: During development, you decide to track timestamps for entries in your playing_with_neon table. You want to quickly add a created_at column.

Check out the video below to see how Cursor and Neon MCP Server can help you add a new column to your database table using natural language commands.

Here's the conversation log between the user and Cursor:

User: In my neon project id: round-salad-44063611 list all the tables
Cursor: I'll help you list all the tables in your Neon project. I'll use the default database name 'neondb' since none was specified.
> Called MCP Tool (get_database_tables)
> I found one table in your database:
> playing_with_neon (in the public schema)
> Would you like to see more details about this table's structure or perform any other operations with it?

User: Can you show me first 5 rows?
Cursor: I'll query the first 5 rows from the playing_with_neon table.
> Called MCP Tool (run_sql)
> Here are the first 5 rows from the table. The table has three columns:
> id (sequential numbers)
> name (string values)
> value (decimal numbers)
> Would you like to perform any other operations with this data?

User: can you add a created_at column?
Cursor: I'll help you add a created_at column to the playing_with_neon table. I'll set it up with a timestamp data type and set it to automatically record the creation time of new rows.
> Called MCP Tool (prepare_database_migration)
> Let me verify the change in the temporary branch to make sure it was applied correctly.
> Called MCP Tool (run_sql)
> I've added the created_at column to the playing_with_neon table in a temporary branch. Would you like to commit this migration to the main branch?
> Migration Details:
> Migration ID: a65babcd-d1cc-401f-89b5-762570570102
> Temporary Branch Name: br-silent-cherry-a1eqrl6i
> Temporary Branch ID: br-silent-cherry-a1eqrl6i
> Migration Result: Success
> Please let me know if you'd like to proceed with applying this change to the main branch.

User: yeah do it
Cursor: I'll complete the migration and apply the changes to the main branch.
> Called MCP Tool (complete_database_migration)
> The migration has been successfully completed! The created_at column has been added to your table in the main branch, and the temporary branch has been cleaned up.

Key takeaways:

• Natural language interaction: You can use simple, conversational English to interact with your database.
• Step-by-step guidance: Cursor (Claude) confirms each step and provides details like branch names and migration IDs.
• MCP Tools in Action: The underlying MCP tools (get_database_tables, run_sql, prepare_database_migration, complete_database_migration) illustrate the automated process.
• Branching for safety: The agent automatically creates a temporary branch for schema changes. The user will be prompted to confirm the migration before applying it to the main branch.

You can verify the changes in your Neon Console or by querying the database directly.

Bonus: Creating a project and branch

Beyond schema changes, you can also manage your Neon projects and branches directly within Cursor using natural language commands. This can be useful for quickly setting up a new development or test environment.

Creating a new project

Let's say you want to create a new Neon project named "my-new-project". You can simply tell Cursor:

User: Create a Neon project named "my-new-project"
Cursor: I'll help you create a new Neon project with the specified name.
> Called MCP Tool (create_project)
> Great! I've created a new Neon project for you with the name "my-new-project". Here are the important details:
> Project ID: orange-dawn-33739962
> Default branch: main
> Default database: neondb
> The project is ready to use. You can start creating tables and working with your database right away.

Cursor will then use the create_project MCP tool to initiate the project creation. It will provide you with a project ID and name.

Creating a New Branch

Once you have a project, you can easily create new branches for development or experimentation. For example, to create a branch named "feature-x" in your "my-new-project" project:

User: Create a branch named "feature-x"
Cursor: Perfect! I've created a new branch named "feature-x". Here are the details:
> Branch ID: br-cold-mountain-a523ka2w
> Branch name: feature-x
> Parent branch ID: br-odd-pine-a5y53krm
> The branch has been created successfully and is ready for use.

Cursor will use the create_branch MCP tool to create the branch and provide you with the branch name and ID. Notice how we don't need to specify the project ID, as Cursor remembers the active project context.

Conclusion

Cursor with Neon MCP Server lets you use natural language to interact with your database and take advantage of Neon's branching capabilities for fast iteration. This approach is ideal for quickly testing database ideas and making schema changes during development.

Resources

• MCP Protocol
• Adding an MCP Server to Cursor
• Neon Docs
• Neon API Keys
• Neon MCP server GitHub