pgcloud

pgcloud

pgcloud 让 MCP 客户端或终端能够访问 Neon Postgres 账户。你可以列出、描述、创建和删除项目及其分支；检查计算端点和组织；并直接查询项目中的任何数据库——包括单条语句、多语句事务、表和列信息查询、慢查询报告以及执行计划。架构变更遵循 Neon 的两阶段模式：先在临时分支上准备迁移或调优会话并进行测试，然后才将其应用到原始分支。

需要 Neon API 密钥。将其放入 NEON_API_KEY 环境变量中；该密钥会作为 Bearer 令牌发送给 Neon API，且绝不会出现在输出中。如果缺少此变量，每次调用都会失败，并指出缺少该变量。

安装

npx @reneturcios/pgcloud list_projects

或者运行容器镜像：

docker run -i -e NEON_API_KEY ghcr.io/cloudcorprecords/pgcloud

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

每个 MCP 工具也都是一个 CLI 子命令。工具参数以单个 JSON 对象的形式通过 --json 传入：

export NEON_API_KEY=<your Neon API key>

pgcloud list_projects
pgcloud list_projects --json '{"limit": 5, "search": "billing"}'
pgcloud describe_project --json '{"projectId": "snowy-pond-12345678"}'
pgcloud create_branch --json '{"projectId": "snowy-pond-12345678", "branchName": "dev"}'
pgcloud run_sql --json '{"projectId": "snowy-pond-12345678", "sql": "select now()"}'
pgcloud get_connection_string --json '{"projectId": "snowy-pond-12345678", "pooled": true}'

pgcloud --version

结果以 JSON 格式输出。退出码：成功时为 0；API 或 SQL 调用失败时为 1（包括缺少 NEON_API_KEY）；用法错误时为 2。

MCP 服务

同一个二进制文件支持这两种用法。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/pgcloud mcp

MCP 客户端配置：

{
  "mcpServers": {
    "pgcloud": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pgcloud", "mcp"],
      "env": { "NEON_API_KEY": "your Neon API key" }
    }
  }
}

工具

工具	输入（粗体为必填项）	功能
list_projects	limit、search、org_id	列出账户中的项目。
describe_project	projectId	描述一个项目。
create_project	name、region_id、org_id	创建一个项目。
delete_project	projectId	删除一个项目及其资源。
create_branch	projectId、branchName、parentBranchId	创建一个带有读写计算的分支。
delete_branch	projectId、branchId	删除一个分支。
describe_branch	projectId、branchId	返回分支记录及其数据库。
list_branch_computes	projectId、branchId	列出计算端点。
list_organizations	search	列出用户可以访问的组织。
get_connection_string	projectId、branchId、databaseName、roleName、pooled	获取 Postgres 连接字符串。
run_sql	sql、projectId、branchId、databaseName、roleName	运行一条 SQL 语句。
run_sql_transaction	sql（数组）、projectId、…	在一个事务中运行多条语句。
get_database_tables	projectId、branchId、databaseName	通过 information_schema 列出表。
describe_table_schema	projectId、tableName、…	列出表的列。
list_slow_queries	projectId、limit、…	返回 pg_stat_statements 中耗时最长的查询。
explain_sql_statement	sql、projectId、…	返回语句的 EXPLAIN 计划。
prepare_database_migration	migrationSql、projectId、…	在临时分支上运行迁移 SQL。
complete_database_migration	migrationId、projectId、…	将已准备的迁移应用到原始分支。
prepare_query_tuning	sql、projectId、…	在临时分支上开启调优会话并生成计划。
complete_query_tuning	tuningId、projectId、applyChanges	结束调优会话，并应用或放弃更改。

管理调用会发送到 https://api.neon.tech/api/v2。SQL 调用会先通过 API 获取分支的连接 URI，然后将语句 POST 到数据库主机的 HTTP SQL 端点，并在 Neon-Connection-String 标头中附上 URI；SQL 文本会按原样传递。迁移和调优会话保存在服务进程中，因此必须由准备会话的同一进程完成会话。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。