项目介绍
技术文档摘要
<picture> <source media="(prefers-color-scheme: dark)" srcset="https://neon.com/brand/neon-logo-dark-color.svg"> <source media="(prefers-color-scheme: light)" srcset="https://neon.com/brand/neon-logo-light-color.svg"> <img width="250px" alt="Neon Logo fallback" src="https://neon.com/brand/neon-logo-dark-color.svg"> </picture>Neon MCP Server
Neon MCP Server 是一个开源工具，允许您使用自然语言与 Neon Postgres 数据库进行交互。
模型上下文协议（MCP）是一种新的标准化协议，旨在管理大型语言模型（LLMs）与外部系统之间的上下文。此仓库提供了一个安装程序和一个针对 Neon 的 MCP 服务器。
Neon 的 MCP 服务器充当自然语言请求与 Neon API 之间的桥梁。基于 MCP 构建，它将您的请求转换为必要的 API 调用，使您能够无缝地执行创建项目和分支、运行查询以及执行数据库迁移等任务。
Neon MCP 服务器的一些关键特性包括：
- 自然语言交互：使用直观的对话命令管理 Neon 数据库。
- 简化数据库管理：无需编写 SQL 或直接使用 Neon API 即可执行复杂操作。
- 非开发者访问：赋予具有不同技术背景的用户与 Neon 数据库交互的能力。
- 数据库迁移支持：利用 Neon 的分支功能，通过自然语言发起数据库模式更改。
例如，在 Claude Desktop 或任何 MCP 客户端中，您可以使用自然语言完成以下 Neon 操作：
让我们创建一个新的 Postgres 数据库，并将其命名为“my-database”。然后创建一个名为 users 的表，包含以下列：id、name、email 和 password。我想在我的名为“my-project”的项目上运行一个迁移，该迁移修改 users 表以添加一个名为“created_at”的新列。你能给我总结一下我的所有 Neon 项目以及每个项目中的数据吗？
[!WARNING] Neon MCP 服务器安全注意事项 Neon MCP 服务器通过自然语言请求提供了强大的数据库管理能力。始终审查并授权 LLM 请求的操作。 确保只有授权用户和应用程序才能访问 Neon MCP 服务器。
Neon MCP 服务器仅适用于本地开发和 IDE 集成。我们不建议在生产环境中使用 Neon MCP 服务器。 它可以执行可能导致意外或未经授权更改的强大操作。
如需更多信息，请参阅 MCP 安全指南 →。
设置 Neon MCP 服务器
连接您的 MCP 客户端到 Neon 有两种选择：
- 远程 MCP 服务器（预览版）：使用 OAuth 进行身份验证，连接到 Neon 管理的 MCP 服务器。这种方法更方便，因为它消除了管理 API 密钥的需求。此外，您将自动收到最新特性和改进。
- 本地 MCP 服务器：在您的机器上本地运行 Neon MCP 服务器，使用 Neon API 密钥进行身份验证。
先决条件
- 一个 MCP 客户端应用程序。
- 一个 Neon 账户。
- Node.js (>= v18.0.0) 和 npm：从 nodejs.org 下载。
对于本地 MCP 服务器设置，还需要一个 Neon API 密钥。请参阅 Neon API 密钥文档，了解如何生成一个。
选项 1. 远程托管 MCP 服务器（预览版）
使用 OAuth 进行身份验证，连接到 Neon 管理的 MCP 服务器。这是最简单的设置，不需要本地安装此服务器，也不需要在客户端配置 Neon API 密钥。
-
在您的客户端 MCP 服务器配置文件（如
mcp.json或mcp_config.json）中添加以下“Neon”条目：{ "mcpServers": { "Neon": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.neon.tech/mcp"] } } } -
保存配置文件。
-
重启或刷新您的 MCP 客户端。
-
浏览器中会打开一个 OAuth 窗口。按照提示授权您的 MCP 客户端访问您的 Neon 账户。
使用 OAuth 基础认证时，默认情况下，MCP 服务器将在您的个人 Neon 账户下的项目上操作。要访问或管理组织下的项目，必须在提示 MCP 客户端时明确提供
org_id或project_id。
远程 MCP 服务器还支持在 Authorization 头中使用 API 密钥进行身份验证，如果您的客户端支持的话：
{
"mcpServers": {
"Neon": {
"url": "https://mcp.neon.tech/mcp",
"headers": {
"Authorization": "Bearer <$NEON_API_KEY>"
}
}
}
}
提供组织的 API 密钥以限制对组织下项目的访问。
只读模式：为了防止意外修改，可以通过添加 x-read-only 头来启用只读模式。这将限制 MCP 服务器仅执行安全且不会破坏的操作：
{
"mcpServers": {
"Neon": {
"url": "https://mcp.neon.tech/mcp",
"headers": {
"Authorization": "Bearer <$NEON_API_KEY>",
"x-read-only": "true"
}
}
}
}
MCP 支持两种远程服务器传输方式：已弃用的 Server-Sent Events (SSE) 和更新推荐的 Streamable HTTP。如果您的 LLM 客户端尚未支持 Streamable HTTP，可以将端点从 https://mcp.neon.tech/mcp 更改为 https://mcp.neon.tech/sse 来使用 SSE。
选项 2. 本地 MCP 服务器
在您的本地机器上使用 Neon API 密钥运行 Neon MCP 服务器。此方法允许您在不依赖远程 MCP 服务器的情况下管理您的 Neon 项目和数据库。
在您的客户端 mcp_config 文件的 mcpServers 部分添加以下 JSON 配置，将 <YOUR_NEON_API_KEY> 替换为您实际的 Neon API 密钥：
{
"mcpServers": {
"neon": {
"command": "npx",
"args": [
"-y",
"@neondatabase/mcp-server-neon",
"start",
"<YOUR_NEON_API_KEY>"
]
}
}
}
故障排除
如果您的客户端不使用 JSON 配置 MCP 服务器（例如旧版本的 Cursor），则可以在提示时使用以下命令：
npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>
Windows 上的故障排除
如果您正在使用 Windows 并在添加 MCP 服务器时遇到问题，可能需要使用命令提示符（cmd）或 Windows 子系统 for Linux（wsl）来运行必要的命令。您的配置设置可能如下所示：
{
"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>"
]
}
}
}
指南
- Neon MCP 服务器指南
- 连接 MCP 客户端到 Neon
- 使用 Neon MCP 服务器的 Cursor
- 使用 Neon MCP 服务器的 Claude Desktop
- 使用 Neon MCP 服务器的 Cline
- 使用 Neon MCP 服务器的 Windsurf
- 使用 Neon MCP 服务器的 Zed
功能
支持的工具
Neon MCP 服务器提供了以下操作，这些操作作为“工具”暴露给 MCP 客户端。您可以使用这些工具通过自然语言命令与您的 Neon 项目和数据库进行交互。
项目管理：
list_projects：列出账户中的前 10 个 Neon 项目，并提供每个项目的摘要。如果找不到特定项目，可以通过传递更高的值给limit参数来增加限制。list_shared_projects：列出与当前用户共享的 Neon 项目。支持搜索参数和限制返回的项目数量（默认：110）。describe_project：获取特定 Neon 项目的详细信息，包括其 ID、名称以及关联的分支和数据库。create_project：在您的 Neon 账户中创建一个新的 Neon 项目。项目充当分支、数据库、角色和计算的容器。delete_project：删除现有的 Neon 项目及其所有相关资源。list_organizations：列出当前用户有权访问的所有组织。可选地使用搜索参数按组织名称或 ID 进行过滤。
分支管理：
create_branch：在指定的 Neon 项目内创建一个新的分支。利用 Neon 的分支 功能进行开发、测试或迁移。delete_branch：从 Neon 项目中删除现有分支。describe_branch：检索特定分支的详细信息，如其名称、ID 和父分支。list_branch_computes：列出项目或特定分支的计算端点，包括计算 ID、类型、大小、最后活跃时间及自动扩展信息。compare_database_schema：显示子分支与其父分支之间的模式差异。reset_from_parent：将当前分支重置为其父分支的状态，丢弃本地更改。如果分支有子分支，则自动保留备份，或者根据请求以自定义名称保留。
SQL 查询执行：
get_connection_string：返回您的数据库连接字符串。run_sql：针对指定的 Neon 数据库执行单个 SQL 查询。支持读写操作。run_sql_transaction：在一个事务中针对 Neon 数据库执行一系列 SQL 查询。get_database_tables：列出指定 Neon 数据库中的所有表。describe_table_schema：检索特定表的模式定义，详细说明列、数据类型和约束。
数据库迁移（模式更改）：
prepare_database_migration：启动数据库迁移过程。关键的是，它创建一个临时分支以安全地应用和测试迁移，然后再影响主分支。complete_database_migration：最终化并应用准备好的数据库迁移至主分支。此操作合并来自临时迁移分支的更改并清理临时资源。
查询性能优化：
list_slow_queries：通过查找数据库中最慢的查询来识别性能瓶颈。需要 pg_stat_statements 扩展。explain_sql_statement：为 SQL 查询提供详细的执行计划，帮助识别性能瓶颈。prepare_query_tuning：分析查询性能并提出优化建议，如创建索引。创建一个临时分支以安全地测试这些优化。complete_query_tuning：最终化查询调优，要么将优化应用于主分支，要么放弃它们。清理临时调优分支。
Neon 认证：
provision_neon_auth：为 Neon 项目配置 Neon 认证。它允许开发人员轻松设置认证基础设施，通过与认证提供商创建集成。
搜索和发现：
search：跨组织、项目和分支搜索匹配查询的内容。返回 ID、标题及直接链接到 Neon 控制台的链接。fetch：使用 ID（通常来自搜索工具）获取特定组织、项目或分支的详细信息。
文档和资源：
load_resource：加载全面的 Neon 文档和使用指南，包括用于设置、配置和最佳实践的“neon-get-started”指南。
迁移
迁移是随着时间管理数据库模式变化的一种方式。借助 Neon MCP 服务器，LLMs 可以通过单独的“开始”（prepare_database_migration）和“提交”（complete_database_migration）命令安全地执行迁移。
“开始”命令接受一个迁移并在一个新临时分支上运行它。返回后，此命令提示 LLM 应该在此分支上测试迁移。然后 LLM 可以运行“提交”命令将迁移应用到原始分支。
开发
使用 MCP CLI 客户端进行开发
迭代 MCP 服务器最简单的方法是使用 mcp-client/。更多详情请参阅 mcp-client/README.md。
npm install
npm run build
npm run watch # 您可以保持这个窗口打开。
cd mcp-client/ && NEON_API_KEY=... npm run start:mcp-server-neon
使用 Claude Desktop（本地 MCP 服务器）进行开发
npm install
npm run build
npm run watch # 您可以保持这个窗口打开。
node dist/index.js init $NEON_API_KEY
然后，每次想要测试更改时，重新启动 Claude。
测试
要运行测试，您需要根据 .env.example 文件设置 .env 文件。
npm run test