Unleash the Power of Natural Language with Neon MCP Server: Seamlessly Integrate LLMs with Your Neon Postgres Databases

Neon MCP Server is an open-source powerhouse that empowers you to interact with your Neon Postgres databases using the intuitive power of natural language. By bridging the gap between human language and database management, it unlocks unprecedented levels of accessibility and efficiency.

At its core, the Neon MCP Server leverages the Model Context Protocol (MCP), a groundbreaking standardized protocol designed to orchestrate context exchange between Large Language Models (LLMs) and external systems. This repository provides both an installer and a fully functional MCP Server meticulously crafted for Neon.

Acting as a sophisticated intermediary, Neon's MCP server intelligently translates natural language requests into precise calls to the Neon API. This seamless translation enables you to effortlessly manage critical tasks such as project and branch creation, query execution, and database migrations, all through the simplicity of conversational commands.

Key Features that Redefine Database Management:

Natural Language Interaction: Experience the future of database management with intuitive, conversational commands that eliminate the need for complex SQL syntax.
Simplified Database Management: Execute intricate actions with ease, bypassing the complexities of manual SQL scripting or direct Neon API interaction.
Enhanced Productivity: Streamline your database administration and development workflows, accelerating project timelines and boosting overall efficiency.
Accessibility for All: Empower users of all technical backgrounds to interact with Neon databases, fostering collaboration and democratizing access to data.
Database Migration Revolution: Harness Neon's powerful branching capabilities to execute database schema changes initiated through natural language, ensuring seamless and risk-free migrations.

Real-World Examples of Natural Language Database Management:

Imagine using Claude Desktop or any MCP Client to effortlessly manage your Neon databases with commands like:

Create a new Postgres database named "my-database" and define a "users" table with columns for id, name, email, and password.
Initiate a migration on my "my-project" project to add a "created_at" column to the users table.
Provide a comprehensive summary of all my Neon projects, including the data contained within each.

[!IMPORTANT] The Neon MCP server grants powerful database management capabilities through natural language requests. Always meticulously review and authorize actions requested by the LLM before execution. Implement robust security measures to ensure that only authorized users and applications have access to the Neon MCP server and Neon API keys.

Getting Started: Connecting Your MCP Client to Neon

Choose the setup option that best suits your needs:

Remote MCP Server (Preview): Connect to Neon's managed MCP server using OAuth for seamless authentication. This streamlined approach eliminates the need for API key management and ensures you always have access to the latest features and improvements.
Local MCP Server: Deploy the Neon MCP server locally on your machine, authenticating with a Neon API key for complete control and customization.

Prerequisites

A compatible MCP Client application.
A valid Neon account.
Node.js (>= v18.0.0) and npm: Ensure you have the latest versions installed from nodejs.org.

For Local MCP Server setup, you'll also need a Neon API key. Refer to the Neon API Keys documentation for detailed instructions on generating one.

Option 1: Remote Hosted MCP Server (Preview)

Effortlessly connect to Neon's managed MCP server using OAuth for authentication. This method simplifies setup, eliminates local server installation, and removes the need for API key configuration within the client.

Add the following "Neon" entry to your client's MCP server configuration file (e.g., mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.neon.tech/sse"
      ]
    }
  }
}

Save the configuration file.
Restart or refresh your MCP client.
An OAuth window will appear in your browser. Follow the prompts to authorize your MCP client to access your Neon account.

Option 2: Local MCP Server

Deploy the Neon MCP server directly on your local machine for maximum control and customization.

Simplified Setup via Smithery:

npx -y @smithery/cli@latest install neon --client <client_name>

You will be prompted to enter your Neon API key. Enter the API key which you obtained from the prerequisites section Replace <client_name> with the name of your MCP client application. Supported client names include:

claude for Claude Desktop
cursor for Cursor (Installing via smithery makes the MCP server a global MCP server in Cursor)
windsurf for Windsurf Editor
roo-cline for Roo Cline VS Code extension
witsy for Witsy
enconvo for Enconvo
vscode for Visual Studio Code (Preview)

Restart your MCP client after installation.

Manual Setup via npm:

If your MCP client is not listed above, manually add the Neon MCP Server details to your client's mcp_config file.

Add the following JSON configuration within the mcpServers section of your client's mcp_config file, replacing <YOUR_NEON_API_KEY> with your actual Neon API key:

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

Troubleshooting

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>

Troubleshooting on Windows

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>"]
    }
  }
}

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

Essential Guides

Feature Deep Dive: Unleashing the Power of MCP Tools

The Neon MCP Server exposes a comprehensive suite of "tools" to MCP Clients, enabling you to interact with your Neon projects and databases using natural language commands.

Project Management:

list_projects: Obtain a comprehensive overview of your Neon projects, including key details for each project associated with your account.
describe_project: Delve into the specifics of a particular Neon project, accessing its ID, name, and associated branches and databases.
create_project: Seamlessly create new Neon projects to serve as containers for branches, databases, roles, and computes.
delete_project: Remove existing Neon projects and all associated resources with a single command.

Branch Management:

create_branch: Leverage Neon's branching capabilities to create new branches within a specified project for development, testing, or migrations.
delete_branch: Remove obsolete branches from your Neon projects.
describe_branch: Retrieve detailed information about a specific branch, including its name, ID, and parent branch.

SQL Query Execution:

get_connection_string: Obtain your database connection string for direct access.
run_sql: Execute individual SQL queries against a specified Neon database, supporting both read and write operations.
run_sql_transaction: Execute a series of SQL queries within a single transaction, ensuring data consistency and integrity.
get_database_tables: List all tables within a specified Neon database for easy exploration.
describe_table_schema: Retrieve the schema definition of a specific table, including columns, data types, and constraints.

Database Migrations (Schema Changes):

prepare_database_migration: Initiate a safe and controlled database migration process by creating a temporary branch to apply and test the migration before affecting the main branch.
complete_database_migration: Finalize and apply a prepared database migration to the main branch, merging changes from the temporary migration branch and cleaning up temporary resources.

Neon Auth:

provision_neon_auth: Streamline the setup of authentication infrastructure for your Neon project by creating an integration with Stack Auth (@stackframe/stack).

Mastering Migrations: A Safe and Controlled Approach

Migrations are essential for managing changes to your database schema over time. The Neon MCP server empowers LLMs to perform migrations safely using distinct "Start" (prepare_database_migration) and "Commit" (complete_database_migration) commands.

The "Start" command accepts a migration and executes it within a new, isolated temporary branch. Upon completion, the command provides guidance to the LLM to thoroughly test the migration on this branch. The LLM can then confidently execute the "Commit" command to apply the migration to the original branch.

Development: Contributing to the Future of Natural Language Database Management

Streamlined Development with MCP CLI Client

The mcp-client/ directory provides an efficient environment for iterating on the MCP Server. Refer to mcp-client/README.md for detailed instructions.

npm install
npm run build
npm run watch # Keep this process running in the background.
cd mcp-client/ && NEON_API_KEY=... npm run start:mcp-server-neon

Development with Claude Desktop (Local MCP Server)

npm install
npm run build
npm run watch # Keep this process running in the background.
node dist/index.js init $NEON_API_KEY

Remember to restart Claude after each code change to test your updates.

Testing: Ensuring Reliability and Performance

To run the tests, configure the .env file based on the provided .env.example file.

npm run test

mcp-server-neon