pgcloud

pgcloud puts a Neon Postgres account within reach of an MCP client or a terminal. Projects and their branches can be listed, described, created, and deleted; compute endpoints and organizations can be inspected; and any database in a project can be queried directly — single statements, multi-statement transactions, table and column introspection, slow-query reports, and execution plans. Schema changes follow Neon's two-phase pattern: a migration or tuning session is prepared on a temporary branch, exercised there, and only then completed onto the original branch.

A Neon API key is required. Put it in the NEON_API_KEY environment variable; it is sent to the Neon API as a Bearer token and never appears in output. When the variable is missing, every call fails with an error that names it.

Install

npx @reneturcios/pgcloud list_projects

Or run the container image:

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

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

Related MCP server: pgsql-mcp-server

CLI

Every MCP tool is also a CLI subcommand. Tool arguments are passed as one JSON object with --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

Results print as JSON. Exit codes: 0 on success, 1 when an API or SQL call fails (including a missing NEON_API_KEY), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/pgcloud mcp

MCP client configuration:

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

Tools

Management calls go to https://api.neon.tech/api/v2. SQL calls first resolve the branch's connection URI from the API, then POST the statement to the database host's HTTP SQL endpoint with the URI in the Neon-Connection-String header; SQL text is passed through as given. Migration and tuning sessions are held in the server process, so a session must be completed by the same process that prepared it.

Development

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

License

MIT — see LICENSE.