NE
OfficialDatabase

Neon MCP Server: Connect to Serverless Postgres

Connect to the Neon MCP server to interact with and manage serverless Postgres databases effortlessly.

View on GitHub
Quick Install
npx -y @neondatabase/mcp-server-neon

Overview

Neon MCP Server is an implementation of a Model Context Protocol (MCP) server that connects LLM-driven tooling and automation directly to serverless Postgres instances hosted on Neon. It acts as an adapter between an MCP-compatible model or agent and a Neon database, exposing safe, auditable tools for running queries, inspecting schemas, and performing database management tasks.

This server is useful when you want to let models interact with live relational data without embedding raw credentials or ad-hoc SQL in prompts. It centralizes connection handling, tool permissions, and logging so model calls map to controlled database operations. Developers can run the server next to their applications, onboard model agents, and use MCP clients to call database-related tools programmatically.

Features

  • Connects MCP-compatible models to Neon serverless Postgres instances
  • Exposes database tools (SQL execution, schema introspection, query planning, etc.)
  • Centralized configuration of database credentials and access controls
  • Runs as a standalone container or local service for development
  • Simple HTTP interface compatible with MCP clients
  • Logging and basic observability for model-driven DB actions

Installation / Configuration

Clone the repository and build or run the provided Docker image. The examples below assume you have Docker installed.

Clone the repo:

git clone https://github.com/neondatabase/mcp-server-neon.git
cd mcp-server-neon

Build and run with Docker:

# Build the container locally
docker build -t mcp-server-neon .

# Run the container, exposing port 8080 (change as needed)
docker run --rm -p 8080:8080 \
  -e DATABASE_URL="postgresql://<user>:<password>@<host>/<database>" \
  -e MCP_PORT=8080 \
  -e LOG_LEVEL=info \
  mcp-server-neon

Run with docker-compose:

version: "3.8"
services:
  mcp-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: "postgresql://<user>:<password>@<host>/<database>"
      MCP_PORT: "8080"
      LOG_LEVEL: "info"

Start:

docker-compose up --build

Local environment variables

  • DATABASE_URL — Postgres connection string for your Neon database (get this from the Neon dashboard).
  • MCP_PORT — Port the MCP server listens on (default: 8080).
  • LOG_LEVEL — Logging verbosity (e.g., debug, info, warn, error).
  • Additional Neon-related credentials — some deployments may require project IDs, API keys, or role settings. Check the repository README or configuration files for the complete list.

Note: Always store secrets (database passwords, API keys) securely (e.g., secret manager, environment variable injection in deployment system).

Available Tools / Resources

The server exposes a set of MCP tools that map to common database actions. Exact tool names and signatures may vary between releases—consult the repository for the definitive list. Typical tools include:

  • sql.execute — Run parameterized SQL queries (read-only or write, depending on configuration)
  • schema.inspect — Return schema metadata (tables, columns, types, indexes)
  • query.explain — Produce EXPLAIN plans for SQL statements
  • connection.health — Check database connectivity and credential validity
  • admin.apply_migration — Apply a migration script (should be restricted in production)

Resources to consult:

  • The repository on GitHub: https://github.com/neondatabase/mcp-server-neon
  • Neon Dashboard: where you create/inspect your serverless Postgres databases and fetch connection strings
  • MCP protocol documentation: for client-side request/response formats and authentication patterns

Use Cases

  1. LLM-assisted data exploration

    • Give an LLM read-only access to a database to answer questions about data distributions, sample rows, or to formulate analytics queries. Use schema.inspect to let the model discover table structures, and sql.execute for controlled queries.
    • Example: ask an assistant to “show me 5 rows from orders where status = ‘pending’”. The agent calls schema.inspect, composes a parameterized SQL query, and calls sql.execute.

  2. Secure query execution from applications

    • Integrate an MCP client in your backend service to let automated agents run predefined queries against your Neon DB without embedding raw credentials into model prompts. Audit logs are centralized on the MCP server.

  3. Migration and maintenance tooling

    • Automate migrations with an admin.apply_migration tool (restrict this in production). Run explain plans and performance checks before applying schema changes.

Example HTTP invocation (illustrative):

curl -X POST http://localhost:8080/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "sql.execute",
    "input": {
      "query": "
Tags:database