MCP HubMCP Hub
neondatabase-labs

mcp-server-neon

by: neondatabase-labs

MCP server for interacting with Neon Management API and databases

184created 29/11/2024
Visit
Neon
API

📌Overview

Purpose: The Neon MCP Server facilitates communication between large language models (LLMs) and external systems using the Model Context Protocol (MCP), simplifying database management via natural language.

Overview: The Neon MCP Server allows users to interact with Neon databases through easily understandable commands, enhancing database management with a user-friendly interface. It supports various commands for creating and managing database schemas, as well as executing migrations safely with the ability to preview changes.

Key Features:

  • Natural Language Commands: Users can perform database operations such as creating databases, running migrations, and summarizing projects using intuitive language commands, which streamlines interaction.

  • Migration Management: The server supports a structured migration process with "Start" and "Commit" commands, enabling safe modifications to database schemas and promoting better testing practices through temporary branches.

Neon MCP Server

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

The Model Context Protocol (MCP) is a new, standardized protocol designed to manage context between large language models (LLMs) and external systems. This repository offers an installer and an MCP Server for Neon.

Neon's MCP server acts as a bridge between natural language requests and the Neon API. Built upon MCP, it translates your requests into the necessary API calls, enabling you to manage tasks such as creating projects and branches, running queries, and performing database migrations seamlessly.

Key Features

  • Natural language interaction: Manage Neon databases using intuitive, conversational commands.
  • Simplified database management: Perform complex actions without writing SQL or directly using the Neon API.
  • Enhanced productivity: Streamline workflows for database administration and development.
  • Accessibility for non-developers: Empower users from varying technical backgrounds.
  • Database migration support: Use Neon's branching capabilities for schema changes initiated via natural language.

Example Commands in MCP Clients

  • Create a new Postgres database and define a table:

    Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with columns: id, name, email, and password.

  • Run a migration to add a new column:

    I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".

  • Summarize your Neon projects:

    Can you give me a summary of all of my Neon projects and what data is in each one?

Note: The Neon MCP server grants powerful database management through natural language. Always review and authorize actions before execution. Restrict access to authorized users and applications only.

Setting up Neon MCP Server

You have two options to connect your MCP client to Neon:

  1. Remote MCP Server (Preview): Connect to Neon's managed MCP server using OAuth. No need to manage API keys. Get automatic updates.

  2. Local MCP Server: Run the Neon MCP server locally, authenticating with a Neon API key.

Prerequisites

For the Local MCP Server setup, you need a Neon API key. See instructions in Neon API Keys documentation.

Option 1. Remote Hosted MCP Server (Preview)

Connect to Neon's managed MCP server using OAuth:

  • Add this "Neon" entry to your MCP client configuration file:

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

  • Save the file and restart your MCP client.

  • An OAuth window will prompt you to authorize access to your Neon account.

Option 2. Local MCP Server

Run Neon MCP server locally.

Setup via Smithery:

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

  • Enter your Neon API key when prompted.

  • Replace <client_name> with your MCP client name. Supported clients:

    • claude
    • cursor
    • windsurf
    • roo-cline
    • witsy
    • enconvo
    • vscode

  • Restart your MCP client after installation.

Setup via npm (Manual)

Add the following to your MCP client's mcp_config file under mcpServers, replacing <YOUR_NEON_API_KEY>:

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

Troubleshooting

Non-JSON MCP Config Clients

Run this command manually:

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

Windows-specific Setup

Use Command Prompt (cmd) or Windows Subsystem for Linux (wsl):

Example for cmd:

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

Example for wsl:

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

Features

Supported Tools

The Neon MCP Server exposes multiple tools for interacting with Neon projects and databases using natural language.

Project Management

  • list_projects: List all Neon projects.
  • describe_project: Get details on a specific project.
  • create_project: Create a new Neon project.
  • delete_project: Delete a Neon project and its resources.

Branch Management

  • create_branch: Create a new branch in a project.
  • delete_branch: Delete a branch.
  • describe_branch: Get branch details.

SQL Query Execution

  • get_connection_string: Retrieve database connection string.
  • run_sql: Execute single SQL query (read/write).
  • run_sql_transaction: Execute multiple SQL queries in a transaction.
  • get_database_tables: List all tables in a database.
  • describe_table_schema: Get schema details of a specific table.

Database Migrations

  • prepare_database_migration: Create a temporary branch and apply migration safely.
  • complete_database_migration: Merge migration branch changes into main branch and clean up.

Neon Auth

  • provision_neon_auth: Set up Neon Auth for authentication infrastructure using Stack Auth integration.

Migrations

Migrations manage changes to your database schema over time. The MCP Server lets LLMs perform migrations safely with:

  • Start (prepare_database_migration): Runs migration in temporary branch.
  • Commit (complete_database_migration): Applies changes to main branch.

Development

Development with MCP CLI Client

The easiest way is using the mcp-client/.

npm install
npm run build
npm run watch # Keep open for live changes.
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 open.
node dist/index.js init $NEON_API_KEY

Restart Claude to test changes.

Testing

Set up .env file based on .env.example.

Run tests:

npm run test