Skip to content
Back to search

postgres-mcp

Connect your coding agent to PostgreSQL. postgres-mcp lets you generate queries and run analytics, design database schemas, diagnose performance of the server and queries, securely manage…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/microsoft--postgres-mcp/badge.svg)](/listings/microsoft--postgres-mcp)

HTML

<a href="/listings/microsoft--postgres-mcp"><img src="/api/listings/microsoft--postgres-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Save a connection profile

Create a named profile once — the password is stored in your OS keyring, never in a config file:

# add a profile from a libpq URI or key=value string
npx -y @microsoft/postgres-mcp connection add local \
  "postgresql://postgres@localhost:5432/postgres"

# store its password securely (hidden prompt)
npx -y @microsoft/postgres-mcp connection set-password local

# check it
npx -y @microsoft/postgres-mcp connection list

> Profiles created by `connection add` permit write tools unless > `access_mode: ro` is set. For autonomous agents that should not write, use an > explicit read-only profile **and** a read-only database role — see > [Read-only profiles](./USAGE.md#read-only-profiles-for-autonomous-agents).

2. Add postgres-mcp to your coding agent

The server speaks MCP over stdio. Point your client at `npx @microsoft/postgres-mcp run` — no credentials go in the client config; the coding agent discovers and connects to your saved profile at runtime.

**GitHub Copilot CLI, Claude Code, Cursor & Claude Desktop** — clients that use the `mcpServers` format (`~/.copilot/mcp-config.json`, `mcp.json`, `.cursor/mcp.json`, `claude_desktop_config.json`, …):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@microsoft/postgres-mcp", "run"]
    }
  }
}

> Running headless or in CI, without a keyring? The server can also take a > database connection string from the environment — see > [Connecting without a profile](./USAGE.md#connecting-without-a-profile) in the > guide.

3. Ask your coding agent

> "List the tables in my PostgreSQL database." > "Show me the 10 most recent orders from my PostgreSQL database." > "What's slowing down my PostgreSQL server right now?"

The agent calls the server's tools (`postgres_mcp_connect`, `postgres_mcp_query`, `postgres_mcp_db_context`, …) for you.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 132 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Postgres MCP Server
  2. [![Platforms: Claude | Copilot | Codex | Open Code](https://img.shields.io/badge/Platforms-Claude_|_Copilot_|_Codex_|_Open_Code-purple.svg)](#2-add-postgres-mcp-to-your-coding-agent)
  3. [![Postgres: local | on-prem | azure | aws | gcp](https://img.shields.io/badge/Postgres-local_|_on--prem_|_azure_|_aws_|_gcp-0f766e.svg)](#requirements)
  4. [![Release status: Preview](https://img.shields.io/badge/Release_status-Preview-blue.svg)](./CHANGELOG.md)
  5. **Connect your coding agent to PostgreSQL.** `postgres-mcp` lets you generate
  6. queries and run analytics, design database schemas, diagnose performance of the
  7. server and queries, securely manage connections, and import data. It is
  8. compatible with any MCP client — GitHub Copilot, Claude Code, Codex, Open Code,
  9. Cursor, VS Code, and more.
  10. - **npm:** https://www.npmjs.com/package/@microsoft/postgres-mcp
  11. - **No install required** — run it straight from `npx`.
  12. ## Quick start
  13. ### 1. Save a connection profile
  14. Create a named profile once — the password is stored in your OS keyring, never in
  15. a config file:
  16. ```sh
  17. # add a profile from a libpq URI or key=value string
  18. npx -y @microsoft/postgres-mcp connection add local \
  19. "postgresql://postgres@localhost:5432/postgres"
  20. # store its password securely (hidden prompt)
  21. npx -y @microsoft/postgres-mcp connection set-password local
  22. # check it
  23. npx -y @microsoft/postgres-mcp connection list
  24. ```
  25. > Profiles created by `connection add` permit write tools unless
  26. > `access_mode: ro` is set. For autonomous agents that should not write, use an
  27. > explicit read-only profile **and** a read-only database role — see
  28. > [Read-only profiles](./USAGE.md#read-only-profiles-for-autonomous-agents).
  29. ### 2. Add postgres-mcp to your coding agent
  30. The server speaks MCP over stdio. Point your client at
  31. `npx @microsoft/postgres-mcp run` — no credentials go in the client config; the
  32. coding agent discovers and connects to your saved profile at runtime.
  33. **GitHub Copilot CLI, Claude Code, Cursor & Claude Desktop** — clients that use the `mcpServers` format (`~/.copilot/mcp-config.json`, `mcp.json`, `.cursor/mcp.json`, `claude_desktop_config.json`, …):
  34. ```jsonc
  35. {
  36. "mcpServers": {
  37. "postgres": {
  38. "command": "npx",
  39. "args": ["-y", "@microsoft/postgres-mcp", "run"]
  40. }
  41. }
  42. }
  43. ```
  44. > Running headless or in CI, without a keyring? The server can also take a
  45. > database connection string from the environment — see
  46. > [Connecting without a profile](./USAGE.md#connecting-without-a-profile) in the
  47. > guide.
  48. ### 3. Ask your coding agent
  49. > "List the tables in my PostgreSQL database."
  50. > "Show me the 10 most recent orders from my PostgreSQL database."
  51. > "What's slowing down my PostgreSQL server right now?"
  52. The agent calls the server's tools (`postgres_mcp_connect`,
  53. `postgres_mcp_query`, `postgres_mcp_db_context`, …) for you.
  54. ---
  55. ## What it can do
  56. | Area | Tools |
  57. |------|-------|
  58. | **Connections** | list / add / remove profiles, connect, disconnect, list databases |
  59. | **Query** | read‑only SQL (`postgres_mcp_query`), DDL/DML (`postgres_mcp_modify`) |
  60. | **Schema** | fetch `CREATE` scripts for tables, indexes, functions, sequences… |
  61. | **Data** | describe a CSV, bulk‑load a CSV via `COPY` |
  62. | **Diagnostics** | probe server capabilities, collect performance metric groups |
  63. See the [usage guide](./USAGE.md) for tools, configuration, authentication
  64. (including Microsoft Entra ID), TLS, and the security model.
  65. ---
  66. ## Security in one minute
  67. - **The server doesn't decide what's allowed — your database does.** It just
  68. passes requests along to PostgreSQL and runs them as the database user in
  69. your connection profile. It can't tell the difference between a request you
  70. meant to make and one the AI invented or was tricked into making, so
  71. anything that database user can do, the AI can do. What actually protects
  72. you is the permissions you give that user, the approval prompts in your MCP
  73. client, and the model you choose to run. See
  74. [Security model](./USAGE.md#security-model) for who's responsible for what,
  75. plus a checklist for locking things down.
  76. - **`postgres_mcp_query` is read‑only.** Omitted profile `access_mode` permits write
  77. tools; set `access_mode: ro` and use a read-only database role unless writes
  78. are intentionally delegated.
  79. - **Microsoft Entra ID (AAD)** is selected automatically for Azure profiles
  80. without a stored keyring password. Store a profile password to use password
  81. authentication instead.
  82. - **Local file reads** (`postgres_mcp_bulk_load_csv`, `postgres_mcp_describe_csv`) are limited
  83. to the MCP server's startup working directory by default and paths allowed
  84. with `allow-access-to-path <path>`. A file allows only itself; a directory
  85. allows recursive access.
  86. - **Secrets are scrubbed** from error messages before they leave the process.
  87. See more info about security model in the [usage guide](./USAGE.md#security-model).
  88. ---
  89. ## Requirements
  90. - **Node.js 22+** (to run via `npx`).
  91. - Linux x64/arm64, macOS x64/arm64, or Windows x64. Windows ARM uses x64
  92. emulation.
  93. - A reachable **PostgreSQL** database — local, Docker, on‑premises, Azure
  94. Database for PostgreSQL, Amazon RDS/Aurora, Google Cloud SQL/AlloyDB, or any
  95. wire‑compatible server.
  96. ## Changelog
  97. See [CHANGELOG.md](./CHANGELOG.md) for release notes.
  98. ## License
  99. This repository is a getting started information package. It is licensed under the [MIT License](https://github.com/microsoft/postgres-mcp/blob/main/LICENSE) © Microsoft. The postgres-mcp project itself is proprietary and its source code is not avialable under MIT license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.