Neon MCP Server (original) (raw)

Manage your Neon Postgres databases using natural language commands with the Neon MCP Server.

The Neon MCP Server is an open-source tool that lets you interact with your Neon Postgres databases in natural language.

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.

The Model Context Protocol (MCP) standardizes communication between LLMs and external tools. It defines a client-server architecture, enabling LLMs (Hosts) to connect to specialized servers that provide context and tools for interacting with external systems. The key components of the MCP architecture are:

Traditionally, connecting AI models to different data sources required developers to create custom code for each integration. This fragmented approach increased development time, maintenance burdens, and limited interoperability between AI models and tools. MCP addresses this challenge by providing a standardized protocol that simplifies integration, accelerates development, and enhances the capabilities of AI assistants.

Neon MCP Server acts as the Server in the MCP architecture, specifically designed for Neon. It provides a set of tools that MCP Clients (like Claude Desktop, Cursor) can utilize to manage Neon resources. This includes actions for project management, branch management, executing SQL queries, and handling database migrations, all driven by natural language requests.

Key Benefits of using 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 and Neon API keys.

You can set up the Neon MCP Server in two ways:

You can use Neon's managed MCP server, available at https://mcp.neon.tech. This is the easiest way to start using the Neon MCP Server. It streamlines the setup process by utilizing OAuth for authentication, eliminating the need to manage Neon API keys directly in your client configuration.

note

The remote hosted MCP server is currently in its preview phase. As the OAuth specification for MCP is still quite new, we are releasing it in this preview state. During the initial weeks, you may experience some adjustments to the setup. However, the instructions provided should be straightforward to follow at this time.

  1. Go to your MCP Client's settings where you configure MCP Servers (this varies by client)
  2. Register a new MCP Server. Add a configuration block for "Neon" under 'mcpServers' key. The configuration should look like this:
{  
  "mcpServers": {  
    "Neon": {  
      "command": "npx",  
      "args": ["-y", "mcp-remote", "https://mcp.neon.tech/sse"]  
    }  
  }  
}

This command uses npx to run a small helper (mcp-remote) that connects to Neon's hosted server endpoint (https://mcp.neon.tech/sse). 3. Save the configuration and restart or refresh your MCP client application. 4. The first time the client initializes Neon's MCP server, it should trigger an OAuth flow:

  1. Your MCP client should now be connected to the Neon Remote MCP Server and ready to use.

You can install Neon MCP server locally using npm or smithey.

note

We recommend using Smithery for installation, as it streamlines the process and guarantees compatibility across MCP clients.

Smithery provides a streamlined method for installing MCP servers.

  1. Open your terminal.
  2. Run the Smithery installation command:
npx -y @smithery/cli install neon --client <client_name>

Replace <client_name> with the name of your MCP client application. Supported client names include: 

npx -y @smithery/cli install neon --client claude

You will be then prompted to enter the Neon API key. 

✔ Successfully resolved neon  
Installing remote server. Please ensure you trust the server author, especially when sharing sensitive data.  
For information on Smithery's data policy, please visit: https://smithery.ai/docs/data-policy  
? The API key for accessing the Neon. You can generate one through the Neon console. (required)  
*********************************************************************  
neon successfully installed for claude
  1. Restart your MCP Client application. For example, if you are using Claude Desktop, quit and reopen the application.

Open your MCP client application and navigate to the settings where you can configure MCP servers. The location of these settings may vary depending on your client. Add a configuration block for "Neon" under the mcpServers key. Your configuration should look like this:

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon", "start", "<YOUR_NEON_API_KEY>"]
    }
  }
}

note

If you are using Windows and encounter issues while adding the MCP server, you might need to use the Command Prompt (cmd) or Windows Subsystem for Linux (wsl) to run the necessary commands. Your configuration setup may resemble the following:

{
  "mcpServers": {
    "neon": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@neondatabase/mcp-server-neon", "start", "<YOUR_NEON_API_KEY>"]
    }
  }
}

If your client does not use JSON for configuration of MCP servers (such as older versions of Cursor), you can use the following command when prompted:

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

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:

Branch management:

SQL query execution:

Database migrations (schema changes):

Query performance tuning:

Neon Auth:

After setting up either the remote or local server and connecting your MCP client, you can start interacting with your Neon databases using natural language.

Example interactions

You can also refer to our individual guides for detailed examples on using the Neon MCP Server with specific MCP clients:

The Neon MCP Server enables natural language interaction with Neon Postgres databases, offering a simplified way to perform database management tasks. You can perform actions such as creating new Neon projects and databases, managing branches, executing SQL queries, and making schema changes, all through conversational requests. Features like branch-based migrations contribute to safer schema modifications. By connecting your preferred MCP client to the Neon MCP Server, you can streamline database administration and development workflows, making it easier for users with varying technical backgrounds to interact with Neon databases.

Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more details, see Getting Support.