{"_id":"@arieffian/postgres-mcp-server","_rev":"2-433060f8add24de11350ba8ac843b323","name":"@arieffian/postgres-mcp-server","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@arieffian/postgres-mcp-server","version":"0.1.0","keywords":["mcp","model-context-protocol","postgres","postgresql","sql","database","llm","claude"],"license":"MIT","_id":"@arieffian/postgres-mcp-server@0.1.0","maintainers":[{"name":"arieffian","email":"donny.arieffian@gmail.com"}],"homepage":"https://github.com/arieffian/postgres-mcp-server#readme","bugs":{"url":"https://github.com/arieffian/postgres-mcp-server/issues"},"bin":{"postgres-mcp-server":"bin/postgres-mcp-server.js"},"dist":{"shasum":"c7a02a921242cfc5ede68c25833bf65f722ba791","tarball":"https://registry.npmjs.org/@arieffian/postgres-mcp-server/-/postgres-mcp-server-0.1.0.tgz","fileCount":67,"integrity":"sha512-WJPJCkvR8phvqj9xmc3kUDtzI4HOkmGkJhmv5H5a32oNvanbbnZQBEnN+SO55EtVWYtv/OeWV52sflHmUJmpRQ==","signatures":[{"sig":"MEYCIQCEofYReErew5Kh9k55xgGlh46Kt9bxAcvzfbZN0BQ+9AIhAKl1pCDRhnvaYu8a6exBiVgYforB3KManikhPadf1nWp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arieffian%2fpostgres-mcp-server@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":83492},"main":"./dist/server.js","type":"module","types":"./dist/server.d.ts","engines":{"node":"^22.22.0 || >= 24.0.0"},"gitHead":"175e7a22c14e9dfc61a00bbf01f8de3a82497033","scripts":{"lint":"eslint . --ext .ts","test":"vitest run tests/unit tests/integration","build":"tsc -p tsconfig.build.json","format":"prettier --write .","typecheck":"tsc --noEmit","ci:publish":"npm publish --provenance --access public","ci:version":"changeset version && npm install --package-lock-only","test:smoke":"vitest run tests/smoke","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"arieffian","email":"donny.arieffian@gmail.com"},"repository":{"url":"git+https://github.com/arieffian/postgres-mcp-server.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server exposing safe, read-only-by-default PostgreSQL access.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"pg":"^8.13.0","zod":"^3.23.8","pino":"^9.5.0","commander":"^12.1.0","zod-to-json-schema":"^3.25.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","eslint":"^8.57.0","vitest":"^3.2.7","prettier":"^3.3.3","@types/pg":"^8.11.10","typescript":"^5.6.3","@types/node":"^22.9.0","@changesets/cli":"^2.27.9","@vitest/coverage-v8":"^3.2.7","@typescript-eslint/parser":"^8.14.0","@testcontainers/postgresql":"^12.1.0","@typescript-eslint/eslint-plugin":"^8.14.0"},"_npmOperationalInternal":{"tmp":"tmp/postgres-mcp-server_0.1.0_1786020536132_0.8409771808014104","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@arieffian/postgres-mcp-server","version":"0.2.0","description":"MCP server exposing safe, read-only-by-default PostgreSQL access.","type":"module","license":"MIT","engines":{"node":"^22.22.0 || >= 24.0.0"},"bin":{"postgres-mcp-server":"bin/postgres-mcp-server.js"},"main":"./dist/server.js","repository":{"type":"git","url":"git+https://github.com/arieffian/postgres-mcp-server.git"},"homepage":"https://github.com/arieffian/postgres-mcp-server#readme","bugs":{"url":"https://github.com/arieffian/postgres-mcp-server/issues"},"keywords":["mcp","model-context-protocol","postgres","postgresql","sql","database","llm","claude"],"scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","test":"vitest run tests/unit tests/integration","test:smoke":"vitest run tests/smoke","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint . --ext .ts","format":"prettier --write .","ci:version":"changeset version && npm install --package-lock-only","ci:publish":"npm publish --provenance --access public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","commander":"^12.1.0","pg":"^8.13.0","pino":"^9.5.0","zod":"^3.23.8","zod-to-json-schema":"^3.25.2"},"devDependencies":{"@changesets/cli":"^2.27.9","@testcontainers/postgresql":"^12.1.0","@types/node":"^22.9.0","@types/pg":"^8.11.10","@typescript-eslint/eslint-plugin":"^8.14.0","@typescript-eslint/parser":"^8.14.0","@vitest/coverage-v8":"^3.2.7","eslint":"^8.57.0","prettier":"^3.3.3","tsx":"^4.19.2","typescript":"^5.6.3","vitest":"^3.2.7"},"_id":"@arieffian/postgres-mcp-server@0.2.0","gitHead":"12c1eb14a5050ec4a3b9825d60b6a60577c18171","types":"./dist/server.d.ts","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-kAc+/fmuCnVBFSNz7iZPwiGeLJGFrPwELzkzHWPrFXKtf4XvGQHQojSwkyREYlr6VrLTCQlHauE/3GGnKEmUFA==","shasum":"17331cd136d9a3b7813bd4b628e28e9db71ec8f7","tarball":"https://registry.npmjs.org/@arieffian/postgres-mcp-server/-/postgres-mcp-server-0.2.0.tgz","fileCount":88,"unpackedSize":107933,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arieffian%2fpostgres-mcp-server@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD7VSUMqn9qTk5jI73n3Unipwk92xnU2thp8qN34HzlcwIhAImEvjTS2+/ySUMbKB+eJVFJrN/08Dl4bPM+w4noE937"}]},"_npmUser":{"name":"arieffian","email":"donny.arieffian@gmail.com"},"directories":{},"maintainers":[{"name":"arieffian","email":"donny.arieffian@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/postgres-mcp-server_0.2.0_1786025396818_0.0022862979771298697"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-06T12:48:55.988Z","modified":"2026-08-06T14:09:57.285Z","0.1.0":"2026-08-06T12:48:56.257Z","0.2.0":"2026-08-06T14:09:56.972Z"},"bugs":{"url":"https://github.com/arieffian/postgres-mcp-server/issues"},"license":"MIT","homepage":"https://github.com/arieffian/postgres-mcp-server#readme","keywords":["mcp","model-context-protocol","postgres","postgresql","sql","database","llm","claude"],"repository":{"type":"git","url":"git+https://github.com/arieffian/postgres-mcp-server.git"},"description":"MCP server exposing safe, read-only-by-default PostgreSQL access.","maintainers":[{"name":"arieffian","email":"donny.arieffian@gmail.com"}],"readme":"# postgres-mcp-server\n\n[![CI](https://github.com/arieffian/postgres-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/arieffian/postgres-mcp-server/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@arieffian/postgres-mcp-server.svg)](https://www.npmjs.com/package/@arieffian/postgres-mcp-server)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nAn MCP server for safely querying PostgreSQL from an LLM. Read-only by default, multi-connection with named aliases, Postgres-session-enforced safety.\n\n## Quickstart\n\nCreate `~/.config/postgres-mcp/config.json`:\n\n```json\n{\n  \"connections\": {\n    \"local\": {\n      \"url_env\": \"LOCAL_DATABASE_URL\",\n      \"mode\": \"read\"\n    }\n  }\n}\n```\n\nAdd to your MCP client config (Claude Desktop, Cursor, Windsurf, Zed):\n\n```json\n{\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@arieffian/postgres-mcp-server\"],\n      \"env\": { \"LOCAL_DATABASE_URL\": \"postgres://user:pw@localhost/db\" }\n    }\n  }\n}\n```\n\nRestart the client and ask: \"Ping the local Postgres and list its tables.\"\n\n## Modes\n\nEvery connection declares its mode statically in config. Escalation requires editing config and restarting.\n\n| Mode  | SELECT | INSERT/UPDATE/DELETE | DDL | Notes |\n|-------|:------:|:--------------------:|:---:|-------|\n| read  |   ✓    |          ✗           |  ✗  | Default. `SET default_transaction_read_only = on` at the session level. |\n| write |   ✓    |          ✓           |  ✗  | Writes must go through `begin_transaction` → `execute` → `commit`. |\n| admin |   ✓    |          ✓           |  ✓  | Same tx flow as write; DDL also permitted. |\n\n## Tools\n\n**Meta**\n- `ping`, `list_connections`\n\n**SQL**\n- `query` — read-only SELECT via server-side cursor\n- `begin_transaction`, `commit`, `rollback` — tx lifecycle\n- `execute` — INSERT/UPDATE/DELETE/DDL inside an open tx\n\n**Schema introspection (Phase 2, new in 0.2.0)**\n- `list_databases`, `list_schemas`\n- `list_tables` — includes regular, partitioned, and foreign tables (via `kind` field); row count is clamped to 0 for never-analyzed tables\n- `list_indexes`, `list_constraints` — per-table catalog listings\n- `list_functions` — excludes functions installed by extensions\n- `describe_table` — composite: columns, PK, FKs, indexes, constraints in one call\n\n**Observability** — ships in Phase 3.\n\n## Safety\n\nFive layers — see [docs/safety.md](docs/safety.md). Highlights:\n\n- Read-only enforced by the Postgres session, not by parsing SQL — we do not trust our own parser.\n- Statement timeout per connection (default 30s).\n- Every SELECT wrapped in a server-side cursor; results capped by row count and byte size.\n- Writes require an explicit transaction; no autocommit.\n- Bound parameter values are never logged. Credentials in URLs are redacted.\n\n## Configuration\n\nDiscovery order (first hit wins):\n\n1. `--config <path>` CLI flag\n2. `$POSTGRES_MCP_CONFIG` env var\n3. `$XDG_CONFIG_HOME/postgres-mcp/config.json` (fallback `~/.config/postgres-mcp/config.json`)\n4. `./postgres-mcp.config.json`\n\n## Contributing\n\nRequires Node ≥ 20. Local dev: `npm install`, `npm test`. Integration tests use `testcontainers` and need a working Docker daemon.\n\n## Publishing\n\nSet `NPM_TOKEN` in the repo's GitHub Actions secrets. Changesets automatically opens a release PR on push to `main`; merging it publishes to npm with provenance.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}