Neon MCP server for AI agents

The Neon MCP Server enables natural language interaction with your Neon Postgres databases through the Model Context Protocol (MCP). It acts as a bridge that translates conversational requests into Neon API calls, allowing you to manage databases without writing SQL or API code.

Installation Options

You have two options for setting up the Neon MCP Server:

Prerequisites

An MCP Client application
A Neon account
Node.js (>= v18.0.0) and npm

Option 1: Remote Hosted MCP Server (Preview)

The easiest setup method using OAuth authentication:

Add the following to your client's MCP server configuration file:

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

Restart your MCP client
Follow the OAuth prompts in your browser to authorize access

For API key authentication with the remote server:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Option 2: Local MCP Server

To run the server locally with your Neon API key:

Add this configuration to your MCP client's config file:

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

Troubleshooting

If your client doesn't use JSON configuration, use this command when prompted:

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

Windows Troubleshooting

On Windows, you might need to modify your configuration to use cmd or WSL:

With Command Prompt:

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

With WSL:

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

Usage Capabilities

The Neon MCP Server provides numerous tools for managing Neon databases through natural language:

Project Management

List, describe, create, and delete Neon projects
List shared projects and organizations

Branch Management

Create, delete, and describe branches
Reset branches to parent state
Compare database schemas between branches

SQL Query Execution

Run SQL queries and transactions
Get database connection strings
List tables and describe table schemas
Identify slow queries

Database Migrations

Safely prepare migrations on temporary branches
Test and apply migrations to main branches

Query Performance Optimization

Explain SQL statements
Analyze and tune query performance
Identify bottlenecks

Example Natural Language Commands

You can use conversational prompts like:

"Create a new Postgres database called 'my-database' with a users table"
"Run a migration on 'my-project' to add a created_at column to the users table"
"Give me a summary of all my Neon projects and their data"

Additional Resources

For more detailed instructions, refer to these guides:

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect