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.
Badge for your README
Markdown
[](/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
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.
- # Postgres MCP Server
- [](#2-add-postgres-mcp-to-your-coding-agent)
- [](#requirements)
- [](./CHANGELOG.md)
- **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 connections, and import data. It is
- compatible with any MCP client — GitHub Copilot, Claude Code, Codex, Open Code,
- Cursor, VS Code, and more.
- - **npm:** https://www.npmjs.com/package/@microsoft/postgres-mcp
- - **No install required** — run it straight from `npx`.
- ## Quick start
- ### 1. Save a connection profile
- Create a named profile once — the password is stored in your OS keyring, never in
- a config file:
- ```sh
- # 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`, …):
- ```jsonc
- {
- "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 it can do
- | Area | Tools |
- |------|-------|
- | **Connections** | list / add / remove profiles, connect, disconnect, list databases |
- | **Query** | read‑only SQL (`postgres_mcp_query`), DDL/DML (`postgres_mcp_modify`) |
- | **Schema** | fetch `CREATE` scripts for tables, indexes, functions, sequences… |
- | **Data** | describe a CSV, bulk‑load a CSV via `COPY` |
- | **Diagnostics** | probe server capabilities, collect performance metric groups |
- See the [usage guide](./USAGE.md) for tools, configuration, authentication
- (including Microsoft Entra ID), TLS, and the security model.
- ---
- ## Security in one minute
- - **The server doesn't decide what's allowed — your database does.** It just
- passes requests along to PostgreSQL and runs them as the database user in
- your connection profile. It can't tell the difference between a request you
- meant to make and one the AI invented or was tricked into making, so
- anything that database user can do, the AI can do. What actually protects
- you is the permissions you give that user, the approval prompts in your MCP
- client, and the model you choose to run. See
- [Security model](./USAGE.md#security-model) for who's responsible for what,
- plus a checklist for locking things down.
- - **`postgres_mcp_query` is read‑only.** Omitted profile `access_mode` permits write
- tools; set `access_mode: ro` and use a read-only database role unless writes
- are intentionally delegated.
- - **Microsoft Entra ID (AAD)** is selected automatically for Azure profiles
- without a stored keyring password. Store a profile password to use password
- authentication instead.
- - **Local file reads** (`postgres_mcp_bulk_load_csv`, `postgres_mcp_describe_csv`) are limited
- to the MCP server's startup working directory by default and paths allowed
- with `allow-access-to-path <path>`. A file allows only itself; a directory
- allows recursive access.
- - **Secrets are scrubbed** from error messages before they leave the process.
- See more info about security model in the [usage guide](./USAGE.md#security-model).
- ---
- ## Requirements
- - **Node.js 22+** (to run via `npx`).
- - Linux x64/arm64, macOS x64/arm64, or Windows x64. Windows ARM uses x64
- emulation.
- - A reachable **PostgreSQL** database — local, Docker, on‑premises, Azure
- Database for PostgreSQL, Amazon RDS/Aurora, Google Cloud SQL/AlloyDB, or any
- wire‑compatible server.
- ## Changelog
- See [CHANGELOG.md](./CHANGELOG.md) for release notes.
- ## License
- 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 inFree to use. If it’s helped, pass it on.