Get started with Claude Desktop and Neon MCP Server (original) (raw)

Imagine managing your database with natural language. Instead of complex SQL, you can simply ask your AI assistant to "create a new table for customer orders" or "show me last quarter's sales figures." This is the power of the Model Context Protocol (MCP), an open standard for AI interaction with external systems.

This guide will introduce you to Neon's MCP server, which allows you to use Large Language Models (LLMs) for intuitive database management. At its core, Neon MCP server allows tools like Claude to easily communicate with the Neon API.

With Neon's MCP server and an LLM like Claude, you can simplify workflows, improve productivity, and manage your Postgres databases more naturally. Let’s explore how this approach can make database management easier and more efficient.

The Model Context Protocol (MCP) is a standard that helps LLMs communicate with external tools, like databases and APIs. It's like a translator, making it easier to connect LLMs to services and data. For the Neon MCP server, it's the protocol that lets Claude (and other LLMs) understand and control your Neon databases through the Neon API.

MCP follows a client-server architecture, where a host application can connect to multiple servers. The key components include:

• Host: These are LLM applications, such as Claude Desktop or integrated development environments (IDEs), that initiate connections to MCP servers
• Client: These reside within the host application and maintain one-to-one connections with individual servers
• Server: These programs provide context, tools, and prompts to clients, enabling access to external data and functionalities

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

Neon's MCP server is an open-source tool that lets LLMs like Claude manage your Neon databases using natural language by interacting with the Neon API. It translates your simple English instructions into Neon API calls.

Examples of natural language commands that are converted to Neon API actions:

• Create a Postgres database called my-database: Calls the Neon API to create a database
• Add a column created_at to the 'users' table in project my-project: Uses the Neon API to run an SQL command
• List all my Neon projects: Calls the Neon API to fetch a project list

Neon MCP server, combined with Neon, offers:

• Simple Setup: Easily connect LLMs to Neon API.
• Natural Language: Manage databases without direct Neon API coding.
• Empowering Non-Developers: Intuitive database interaction for everyone.

warning

The Neon MCP server's ability to execute arbitrary commands from natural language requests requires careful attention to security. Always review and approve actions before they are committed. Grant access only to authorized users and applications.

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:

• list_projects: Retrieves a list of your Neon projects, providing a summary of each project associated with your Neon account. Supports limiting the number of projects returned (default: 10).
• describe_project: Fetches detailed information about a specific Neon project, including its ID, name, and associated branches and databases.
• create_project: Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes.
• delete_project: Deletes an existing Neon project and all its associated resources.

Branch management:

• create_branch: Creates a new branch within a specified Neon project. Leverages Neon's branching feature for development, testing, or migrations.
• delete_branch: Deletes an existing branch from a Neon project.
• describe_branch: Retrieves details about a specific branch, such as its name, ID, and parent branch.
• list_branch_computes: Lists compute endpoints for a project or specific branch, including compute ID, type, size, and autoscaling information.

SQL query execution:

• get_connection_string: Returns your database connection string.
• run_sql: Executes a single SQL query against a specified Neon database. Supports both read and write operations.
• run_sql_transaction: Executes a series of SQL queries within a single transaction against a Neon database.
• get_database_tables: Lists all tables within a specified Neon database.
• describe_table_schema: Retrieves the schema definition of a specific table, detailing columns, data types, and constraints.
• list_slow_queries: Identifies performance bottlenecks by finding the slowest queries in a database. Requires the pg_stat_statements extension.

Database migrations (schema changes):

• prepare_database_migration: Initiates a database migration process. Critically, it creates a temporary branch to apply and test the migration safely before affecting the main branch.
• complete_database_migration: Finalizes and applies a prepared database migration to the main branch. This action merges changes from the temporary migration branch and cleans up temporary resources.

Query performance tuning:

• explain_sql_statement: Analyzes a SQL query and returns detailed execution plan information to help understand query performance.
• prepare_query_tuning: Identifies potential performance issues in a SQL query and suggests optimizations. Creates a temporary branch for testing improvements.
• complete_query_tuning: Finalizes and applies query optimizations after testing. Merges changes from the temporary tuning branch to the main branch.

Neon Auth:

• provision_neon_auth: Provisions Neon Auth for a Neon project. Sets up authentication infrastructure by creating an integration with Stack Auth (@stackframe/stack).

These actions enable any MCP Host to interact with various functionalities of the Neon platform via the Neon API. Certain tools, especially database migration ones, are tailored for AI agent and LLM usage, leveraging Neon’s branching for safe preview and commit.

We'll use Claude Desktop to interact with Neon MCP server. Here's how to set it up:

• Node.js (>= v18): Install from nodejs.org.
• Claude Desktop: Install Anthropic's Claude Desktop.
• Neon Account: Sign up for a free Neon account at neon.tech.
• Neon API Key (for Local MCP server):: Get your Neon API Key.

You have two options for connecting Claude to the Neon MCP Server:

1. Remote MCP Server (Preview): Connect to Neon's managed MCP server using OAuth for authentication. This method is more convenient as it eliminates the need to manage API keys in Claude. Additionally, you will automatically receive the latest features and improvements as soon as they are released.
2. Local MCP Server: Run the Neon MCP server locally on your machine, authenticating with a Neon API key.
3. Open Claude desktop and navigate to Settings.
4. Under the Developer tab, click Edit Config (On Windows, it's under File -> Settings -> Developer -> Edit Config) to open the location of configuration file (claude_desktop_config.json).
5. Open the claude_desktop_config.json file in a text editor of your choice.
6. Add the "Neon" server entry within the mcpServers object:

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

1. Save the configuration file and restart Claude Desktop.
2. An OAuth window will open in your browser. Follow the prompts to authorize Claude to access your Neon account.
3. After authorization, you can start using the Neon MCP server with Claude.

note

The remote hosted MCP server is in preview due to the new OAuth MCP specification, expect potential changes as we continue to refine the OAuth integration.

This method runs the Neon MCP server locally on your machine, using a Neon API key for authentication.

1. Open your terminal.
2. Run the following command to install the Neon MCP server. This command uses the @smithery/cli package to install the Neon MCP server and configure it for use with Claude.

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

You will be prompted to enter your Neon API key during the installation process. You can enter the API key which you obtained from the prerequisites section. You should see output similar to this:

npx -y @smithery/cli@latest install neon --client claude  
✔ 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 Claude Desktop. You can do so by quitting the Claude Desktop and opening it again.

You can verify that the connection to the Neon MCP server either remote or local is successful by following these steps:

1. In Claude hover over the 🔨 icon to see the available tools.
2. Click on the icon to see the list of available tools in detail. You should see the Neon MCP server's tools listed.
3. Claude is now connected to Neon's remote MCP server.

Ask Claude "List my Neon projects". If it works, you'll see your projects listed by Claude, fetched using the Neon API. For example, you might see output similar to this:

Neon MCP server lets you manage Neon via Neon API calls

• List databases: "What databases do I have in my Neon project?"
• Create a new Neon project: "Create a new Neon named my-project"
• Create a new database: "Create a new database called my-database in the Neon project named my-project"
• Insert records" "Create a table named posts with 20 records."
• Query a table: "Show me 10 posts from 'posts' table in database 'my-database' of project 'my-project'" (Triggers run_sql action to execute query)
• List tables: "What tables are in database 'my-database' of project 'my-project'?" (Triggers get_database_tables action to get table list)
• Table schema: "Show schema of 'posts' table in database 'my-database' of project 'my-project'" (Triggers describe_table_schema action to describe schema)

Imagine you want to add a column to a table in your Neon project. Instead of writing SQL migrations and directly calling the Neon API, with Neon MCP server and Claude, you can say: "In my social network Neon project, edit the posts table and add a deleted_at column."

Using Neon MCP server, Claude will:

1. Confirm project: Check which project you are referring to.
2. Check schema: Look at the posts table structure.
3. Make migration: Create the SQL to add the column
4. Preview changes: Show you the changes in a safe, temporary branch leveraging Neon's branching feature.
5. Apply changes: After you approve, apply the change to your database.
6. Confirm success: Tell you the column is added and prompt you to commit the migration.

This shows how Neon MCP server simplifies and makes database management safer with natural language, all powered by the Neon API under the hood.

Neon MCP server can be used in various scenarios. Here are just a few possibilities:

• SaaS apps: Faster development with natural language database management
• Dev/Test: Quick database setup for testing
• AI agents: Simple database backend for AI using natural language
• Internal tools: Data access for non-technical teams via natural language interaction

When Claude uses the Neon MCP tool, you'll see an authorization prompt: "Allow tool from "neon"?"

For your security, review the tool's purpose before permitting the operation to proceed. Remember that LLMs can sometimes produce unexpected results, so careful monitoring is always recommended.

Neon MCP server makes database management conversational and easier by enabling natural language interaction with the Neon API. It simplifies tasks, automates processes, and opens new ways to use AI with databases.

• MCP Protocol
• Neon Docs
• Neon API Reference
• Neon API Keys
• Neon MCP server GitHub

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.