Skip to content
Back to search

postgresql-mcp-server

A Powerful PostgreSQL MCP server with 14 consolidated database management tools for AI assistants.

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/henkdz--postgresql-mcp-server/badge.svg)](/listings/henkdz--postgresql-mcp-server)

HTML

<a href="/listings/henkdz--postgresql-mcp-server"><img src="/api/listings/henkdz--postgresql-mcp-server/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.

npx @henkey/postgres-mcp-server --help

Add to your MCP client configuration:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "npx",
      "args": [
        "@henkey/postgres-mcp-server",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Option 2: Install via Smithery

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Option 3: Docker (Recommended for Production)

# Build the Docker image
docker build -t postgres-mcp-server .

# Run with environment variable
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  postgres-mcp-server

Add to your MCP client configuration:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "henkey/postgres-mcp:latest",
        "-e",
        "POSTGRES_CONNECTION_STRING"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

Option 4: Manual Installation (Development)

git clone <repository-url>
cd postgresql-mcp-server
npm install
npm run build

Add to your MCP client configuration:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "node",
      "args": [
        "/path/to/postgresql-mcp-server/build/index.js",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Security Modes

The server now starts in `readonly` mode by default. Tools may still be listed for MCP discovery, but every call is classified and checked before it reaches the database.

| Mode | Allows | Blocks by default | | ---- | ------ | ----------------- | | `readonly` | schema inspection, analysis, monitoring, SELECT-style query tools | mutations, DDL, role changes, filesystem import/export, arbitrary SQL | | `write` | readonly operations plus data mutations | DDL, role changes, filesystem import/export, arbitrary SQL | | `admin` | write operations plus schema, index, function, trigger, RLS, role, and filesystem tools | arbitrary SQL | | `unsafe` | all tool categories, including arbitrary SQL | destructive operations unless explicitly allowed |

Destructive operations such as drops, resets, and arbitrary SQL also require explicit opt-in:

# Default: readonly, no per-tool connection strings
npx @henkey/postgres-mcp-server --connection-string "postgresql://readonly_user:pass@host:5432/db"

# Enable DML mutations, but still block DDL/admin/arbitrary SQL
npx @henkey/postgres-mcp-server --security-mode write --connection-string "postgresql://app_writer:pass@host:5432/db"

# Enable admin tools and destructive operations
npx @henkey/postgres-mcp-server --security-mode admin --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

# Enable arbitrary SQL only for trusted local/admin use
npx @henkey/postgres-mcp-server --security-mode unsafe --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

Per-tool `connectionString`, `sourceConnectionString`, and `targetConnectionString` arguments are disabled by default. Prefer a fixed server-level connection string with a least-privilege PostgreSQL role. For development only, enable per-tool connection strings with `--allow-tool-connection-string` or `POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true`. Explicit per-tool, CLI, and `POSTGRES_CONNECTION_STRING` values must be non-empty strings. Blank higher-priority connection strings fail validation instead of falling back to lower-priority sources.

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 · 495 lines

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

  1. # PostgreSQL MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@HenkDz/postgresql-mcp-server)](https://smithery.ai/server/@HenkDz/postgresql-mcp-server)
  3. <a href="https://glama.ai/mcp/servers/@HenkDz/postgresql-mcp-server">
  4. <img width="380" height="200" src="https://glama.ai/mcp/servers/@HenkDz/postgresql-mcp-server/badge" alt="PostgreSQL Server MCP server" />
  5. </a>
  6. A Model Context Protocol (MCP) server that provides comprehensive PostgreSQL database management capabilities for AI assistants.
  7. **🚀 What's New**: This server has been completely redesigned from 46 individual tools to 18 intelligent tools through consolidation (34→8 meta-tools) and enhancement (+4 new tools), providing better AI discovery while adding powerful data manipulation and comment management capabilities.
  8. ## Breaking Changes in 2.0.0
  9. Version 2.0.0 introduces security boundaries that intentionally change default behavior from the 1.x line:
  10. - The server starts in `readonly` mode. Mutations, DDL, role administration, filesystem import/export, and arbitrary SQL require `--security-mode write`, `--security-mode admin`, or `--security-mode unsafe` as appropriate.
  11. - Destructive operations such as drops, resets, broad role grants, and arbitrary SQL require `--allow-destructive`.
  12. - Per-tool `connectionString`, `sourceConnectionString`, and `targetConnectionString` arguments are disabled by default. Use server-level `--connection-string` or `POSTGRES_CONNECTION_STRING`, or explicitly opt in with `--allow-tool-connection-string`.
  13. - Legacy string `where` clauses are rejected for mutation, index, export, and copy filters. Use structured `where` predicates, or `rawWhere` only with `--security-mode unsafe --allow-destructive`.
  14. - Multi-statement `pg_execute_sql` calls must use `transactional: true`, `expectRows: false`, and no bind `parameters`.
  15. - Tool schemas reject unknown fields, so misspelled or unintended inputs fail before connection resolution.
  16. - User and target identifiers are restricted to safe simple PostgreSQL identifiers.
  17. For the non-breaking security patch line, use `@henkey/postgres-mcp-server@1.0.7`.
  18. ## Quick Start
  19. ## Prerequisites
  20. - Node.js ≥18.0.0
  21. - Access to a PostgreSQL server
  22. - (Optional) An MCP client like Cursor or Claude for AI integration
  23. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=postgresql-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZW5rZXkvcG9zdGdyZXMtbWNwLXNlcnZlciIsIi0tY29ubmVjdGlvbi1zdHJpbmciLCJwb3N0Z3Jlc3FsOi8vdXNlcjpwYXNzd29yZEBob3N0OnBvcnQvZGF0YWJhc2UiXX0=)
  24. ### Option 1: npm (Recommended)
  25. ```bash
  26. # Install globally
  27. npm install -g @henkey/postgres-mcp-server
  28. # Or run directly with npx (no installation)
  29. # Use env var for connection string (optional)
  30. export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db"
  31. npx @henkey/postgres-mcp-server
  32. # Or pass directly:
  33. npx @henkey/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/db"
  34. ```
  35. # Verify installation
  36. npx @henkey/postgres-mcp-server --help
  37. Add to your MCP client configuration:
  38. ```json
  39. {
  40. "mcpServers": {
  41. "postgresql-mcp": {
  42. "command": "npx",
  43. "args": [
  44. "@henkey/postgres-mcp-server",
  45. "--connection-string", "postgresql://user:password@host:port/database"
  46. ]
  47. }
  48. }
  49. }
  50. ```
  51. ### Option 2: Install via Smithery
  52. ```bash
  53. npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude
  54. ```
  55. ### Option 3: Docker (Recommended for Production)
  56. ```bash
  57. # Build the Docker image
  58. docker build -t postgres-mcp-server .
  59. # Run with environment variable
  60. docker run -i --rm \
  61. -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  62. postgres-mcp-server
  63. ```
  64. Add to your MCP client configuration:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "postgresql-mcp": {
  69. "command": "docker",
  70. "args": [
  71. "run",
  72. "-i",
  73. "--rm",
  74. "henkey/postgres-mcp:latest",
  75. "-e",
  76. "POSTGRES_CONNECTION_STRING"
  77. ],
  78. "env": {
  79. "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
  80. }
  81. }
  82. }
  83. }
  84. ```
  85. ### Option 4: Manual Installation (Development)
  86. ```bash
  87. git clone <repository-url>
  88. cd postgresql-mcp-server
  89. npm install
  90. npm run build
  91. ```
  92. Add to your MCP client configuration:
  93. ```json
  94. {
  95. "mcpServers": {
  96. "postgresql-mcp": {
  97. "command": "node",
  98. "args": [
  99. "/path/to/postgresql-mcp-server/build/index.js",
  100. "--connection-string", "postgresql://user:password@host:port/database"
  101. ]
  102. }
  103. }
  104. }
  105. ```
  106. ## Security Modes
  107. The server now starts in `readonly` mode by default. Tools may still be listed for MCP discovery, but every call is classified and checked before it reaches the database.
  108. | Mode | Allows | Blocks by default |
  109. | ---- | ------ | ----------------- |
  110. | `readonly` | schema inspection, analysis, monitoring, SELECT-style query tools | mutations, DDL, role changes, filesystem import/export, arbitrary SQL |
  111. | `write` | readonly operations plus data mutations | DDL, role changes, filesystem import/export, arbitrary SQL |
  112. | `admin` | write operations plus schema, index, function, trigger, RLS, role, and filesystem tools | arbitrary SQL |
  113. | `unsafe` | all tool categories, including arbitrary SQL | destructive operations unless explicitly allowed |
  114. Destructive operations such as drops, resets, and arbitrary SQL also require explicit opt-in:
  115. ```bash
  116. # Default: readonly, no per-tool connection strings
  117. npx @henkey/postgres-mcp-server --connection-string "postgresql://readonly_user:pass@host:5432/db"
  118. # Enable DML mutations, but still block DDL/admin/arbitrary SQL
  119. npx @henkey/postgres-mcp-server --security-mode write --connection-string "postgresql://app_writer:pass@host:5432/db"
  120. # Enable admin tools and destructive operations
  121. npx @henkey/postgres-mcp-server --security-mode admin --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"
  122. # Enable arbitrary SQL only for trusted local/admin use
  123. npx @henkey/postgres-mcp-server --security-mode unsafe --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"
  124. ```
  125. Per-tool `connectionString`, `sourceConnectionString`, and `targetConnectionString` arguments are disabled by default. Prefer a fixed server-level connection string with a least-privilege PostgreSQL role. For development only, enable per-tool connection strings with `--allow-tool-connection-string` or `POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true`.
  126. Explicit per-tool, CLI, and `POSTGRES_CONNECTION_STRING` values must be non-empty strings. Blank higher-priority connection strings fail validation instead of falling back to lower-priority sources.
  127. Optionally restrict all server-level and per-tool connection strings to an allowlist with `--allowed-connection-target`, `allowedConnectionTargets`, or `POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS`. Target patterns use `[user@]host[:port][/database]`; omitted fields are unconstrained and `*` is allowed only as a full-field wildcard, for example `readonly@db.internal:5432/app` or `*@localhost:*/dev`.
  128. For deployment grants, see [PostgreSQL Role Templates](./docs/POSTGRES_ROLES.md). The templates split readonly, writer, schema-admin, and role-admin credentials so the PostgreSQL role remains aligned with the selected MCP `securityMode`.
  129. Security settings can also be placed in the tools config file:
  130. ```json
  131. {
  132. "securityMode": "readonly",
  133. "allowDestructive": false,
  134. "allowToolConnectionString": false,
  135. "workspaceDir": "/path/to/mcp-workspace",
  136. "auditFile": "/path/to/postgres-mcp-audit.jsonl",
  137. "maxConnections": 20,
  138. "idleTimeoutMillis": 30000,
  139. "connectionTimeoutMillis": 2000,
  140. "maxFileBytes": 10485760,
  141. "statementTimeoutMs": 30000,
  142. "queryTimeoutMs": 45000,
  143. "lockTimeoutMs": 10000,
  144. "idleInTransactionSessionTimeoutMs": 60000,
  145. "allowedConnectionTargets": [
  146. "readonly@db.internal:5432/app"
  147. ],
  148. "enabledTools": [
  149. "pg_analyze_database",
  150. "pg_manage_schema",
  151. "pg_execute_query"
  152. ]
  153. }
  154. ```
  155. Runtime configuration precedence is CLI options, then the tools config file, then environment variables. Explicit `false` values in the tools config override enabling environment variables such as `POSTGRES_MCP_ALLOW_DESTRUCTIVE=true`.
  156. If a tools config path is provided, the server treats it as required: unreadable, malformed, non-object, incorrectly typed, unknown-key, invalid `securityMode`, or unknown `enabledTools` entries stop startup instead of falling back to all available tools.
  157. CLI options:
  158. - `--version`
  159. - `--connection-string`
  160. - `--tools-config`
  161. - `--security-mode`
  162. - `--allow-destructive`
  163. - `--allow-tool-connection-string`
  164. - `--workspace-dir`
  165. - `--audit-file`
  166. - `--max-connections`
  167. - `--idle-timeout-ms`
  168. - `--connection-timeout-ms`
  169. - `--max-file-bytes`
  170. - `--statement-timeout-ms`
  171. - `--query-timeout-ms`
  172. - `--lock-timeout-ms`
  173. - `--idle-in-transaction-session-timeout-ms`
  174. - `--allowed-connection-target`
  175. Environment variables:
  176. - `POSTGRES_TOOLS_CONFIG=/path/to/tools.json`
  177. - `POSTGRES_MCP_SECURITY_MODE=readonly|write|admin|unsafe`
  178. - `POSTGRES_MCP_ALLOW_DESTRUCTIVE=true`
  179. - `POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true`
  180. - `POSTGRES_MCP_WORKSPACE_DIR=/path/to/mcp-workspace`
  181. - `POSTGRES_MCP_AUDIT_FILE=/path/to/postgres-mcp-audit.jsonl`
  182. - `POSTGRES_MCP_MAX_CONNECTIONS=20`
  183. - `POSTGRES_MCP_IDLE_TIMEOUT_MS=30000`
  184. - `POSTGRES_MCP_CONNECTION_TIMEOUT_MS=2000`
  185. - `POSTGRES_MCP_MAX_FILE_BYTES=10485760`
  186. - `POSTGRES_MCP_STATEMENT_TIMEOUT_MS=60000`
  187. - `POSTGRES_MCP_QUERY_TIMEOUT_MS=65000`
  188. - `POSTGRES_MCP_LOCK_TIMEOUT_MS=10000`
  189. - `POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS=60000`
  190. - `POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS=readonly@db.internal:5432/app,*@localhost:*/dev`
  191. - `POSTGRES_MCP_DEBUG_SQL=true` to opt into verbose `pg-monitor` SQL tracing. This may log raw SQL and bind values, so leave it disabled unless you are debugging a trusted local database.
  192. Boolean environment flags must be exactly `true` or `false` when set.
  193. Numeric resource settings from CLI, tools config, or environment variables must be positive integers. Runtime defaults use a 20-connection pool, a 30000 ms pool idle timeout, a 2000 ms connection timeout, a 60000 ms PostgreSQL `statement_timeout`, a 65000 ms node-postgres query timeout, a 10000 ms PostgreSQL `lock_timeout`, and a 60000 ms PostgreSQL `idle_in_transaction_session_timeout`. Pool and timeout settings can be raised or lowered with `--max-connections`, `--idle-timeout-ms`, `--connection-timeout-ms`, `--statement-timeout-ms`, `--query-timeout-ms`, `--lock-timeout-ms`, `--idle-in-transaction-session-timeout-ms`, `maxConnections`, `idleTimeoutMillis`, `connectionTimeoutMillis`, `statementTimeoutMs`, `queryTimeoutMs`, `lockTimeoutMs`, `idleInTransactionSessionTimeoutMs`, `POSTGRES_MCP_MAX_CONNECTIONS`, `POSTGRES_MCP_IDLE_TIMEOUT_MS`, `POSTGRES_MCP_CONNECTION_TIMEOUT_MS`, `POSTGRES_MCP_STATEMENT_TIMEOUT_MS`, `POSTGRES_MCP_QUERY_TIMEOUT_MS`, `POSTGRES_MCP_LOCK_TIMEOUT_MS`, or `POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`.
  194. Explicit connection string, `workspaceDir`, `auditFile`, `--workspace-dir`, and `--audit-file` values must be non-empty strings.
  195. Connection target allowlists are enforced before tool execution for per-tool connection strings and during connection resolution for server-level sources. When an allowlist is configured, connection strings must be PostgreSQL URL or keyword-style strings with an explicit `host` or `hostaddr`.
  196. Mutation, index, export, and copy filters should use structured `where` predicates. Legacy string `where` clauses are rejected; the explicit `rawWhere` escape hatch is treated as arbitrary SQL and requires `--security-mode unsafe --allow-destructive`.
  197. EXPLAIN tools only accept one read-only statement and run inside a read-only transaction. `analyze: true` still requires unsafe mode because PostgreSQL executes the supplied query to collect runtime statistics.
  198. Multi-statement `pg_execute_sql` calls must use `transactional: true`, `expectRows: false`, and no bind `parameters`. Use a single parameterized statement or CTE when bind parameters are needed.
  199. Error messages, diagnostics, and catalog metadata are sanitized by default. SQL text from `pg_stat_statements`, function definitions, RLS predicates, check constraints, index definitions, and column defaults are redacted unless they are intentionally returned as user data.
  200. Data execution, query/performance, schema, index, constraint, user/permission, trigger, comment, function, RLS, migration, and diagnostic tools reject unknown input fields so misspelled or unintended parameters fail before connection resolution.
  201. Denied security-boundary requests emit one structured stderr line prefixed with `[MCP Audit]`. Audit events include sanitized fields such as `toolName`, `reason`, `securityMode`, `risk`, and whether per-tool connection strings were present; they do not log raw SQL, full request payloads, or connection-string passwords. Set `POSTGRES_MCP_AUDIT_FILE`, `--audit-file`, or `auditFile` to append the same sanitized audit events to a JSONL file.
  202. Filesystem tools such as table export/import require a workspace directory and only read or write `.json` and `.csv` files inside it:
  203. ```bash
  204. npx @henkey/postgres-mcp-server \
  205. --security-mode admin \
  206. --allow-destructive \
  207. --workspace-dir /path/to/mcp-workspace \
  208. --connection-string "postgresql://admin_user:pass@host:5432/db"
  209. ```
  210. ## What's Included
  211. **18 powerful tools** organized into three categories:
  212. - **🔄 Consolidation**: 34 original tools consolidated into 8 intelligent meta-tools
  213. - **🔧 Specialized**: 6 tools kept separate for complex operations
  214. - **🆕 Enhancement**: 4 brand new tools (not in original 46)
  215. ### 📊 **Consolidated Meta-Tools** (8 tools)
  216. - **Schema Management** - Tables, columns, ENUMs, constraints
  217. - **User & Permissions** - Create users, grant/revoke permissions
  218. - **Query Performance** - EXPLAIN plans, slow queries, statistics
  219. - **Index Management** - Create, analyze, optimize indexes
  220. - **Functions** - Create, modify, manage stored functions
  221. - **Triggers** - Database trigger management
  222. - **Constraints** - Foreign keys, checks, unique constraints
  223. - **Row-Level Security** - RLS policies and management
  224. ### 🚀 **Enhancement Tools** (4 NEW tools)
  225. *Brand new capabilities not available in the original 46 tools*
  226. - **Execute Query** - SELECT operations with count/exists support
  227. - **Execute Mutation** - INSERT/UPDATE/DELETE/UPSERT operations
  228. - **Execute SQL** - Arbitrary SQL execution with transaction support
  229. - **Comments Management** - Comprehensive comment management for all database objects
  230. ### 🔧 **Specialized Tools** (6 tools)
  231. - **Database Analysis** - Performance and configuration analysis
  232. - **Debug Database** - Troubleshoot connection, performance, locks
  233. - **Data Export** - JSON/CSV data export
  234. - **Data Import** - JSON/CSV data import
  235. - **Copy Between Databases** - Cross-database data transfer
  236. - **Real-time Monitoring** - Live database metrics and alerts
  237. ## Example Usage
  238. ```typescript
  239. // Analyze database performance
  240. { "analysisType": "performance", "schema": "public" }
  241. // Create a table with constraints
  242. {
  243. "operation": "create_table",
  244. "tableName": "users",
  245. "columns": [
  246. { "name": "id", "type": "SERIAL PRIMARY KEY" },
  247. { "name": "email", "type": "VARCHAR(255) UNIQUE NOT NULL" }
  248. ]
  249. }
  250. // Query data with parameters
  251. {
  252. "operation": "select",
  253. "query": "SELECT * FROM users WHERE created_at > $1",
  254. "parameters": ["2024-01-01"],
  255. "limit": 100
  256. }
  257. // Select results are always bounded: default limit 100, max 1000.
  258. // Insert new data
  259. {
  260. "operation": "insert",
  261. "table": "users",
  262. "data": {"name": "John Doe", "email": "john@example.com"},
  263. "returning": "*",
  264. "maxReturningRows": 100
  265. }
  266. // Mutation RETURNING output is capped in the response: default 100, max 1000.
  267. // Find slow queries
  268. {
  269. "operation": "get_slow_queries",
  270. "limit": 5,
  271. "minDuration": 100
  272. }
  273. // Execute a parameterized SELECT query
  274. {
  275. "operation": "select",
  276. "query": "SELECT * FROM users WHERE id = $1",
  277. "parameters": [1]
  278. }
  279. // Perform an INSERT mutation
  280. {
  281. "operation": "insert",
  282. "table": "products",
  283. "data": {"name": "New Product", "price": 99.99},
  284. "returning": "id",
  285. "maxReturningRows": 100
  286. }
  287. // Perform an UPDATE mutation with a structured WHERE predicate
  288. {
  289. "operation": "update",
  290. "table": "products",
  291. "data": {"price": 89.99},
  292. "where": {"id": 123},
  293. "returning": ["id", "price"]
  294. }
  295. // Manage database object comments
  296. {
  297. "operation": "set",
  298. "objectType": "table",
  299. "objectName": "users",
  300. "comment": "Main user account information table"
  301. }
  302. ```
  303. ## 📚 Documentation
  304. **📋 [Complete Tool Schema Reference](./TOOL_SCHEMAS.md)** - All 18 tool parameters & examples in one place
  305. For additional information, see the [`docs/`](./docs/) folder:
  306. - **[🔐 Security Posture](./SECURITY.md)** - Sandboxing, approvals, audit events, and deployment posture
  307. - **[PostgreSQL Role Templates](./docs/POSTGRES_ROLES.md)** - Least-privilege database roles for each deployment profile
  308. - **[📖 Usage Guide](./docs/USAGE.md)** - Hardened usage patterns and examples
  309. - **[🛠️ Development Guide](./docs/DEVELOPMENT.md)** - Setup and release checklist
  310. - **[⚙️ Technical Details](./docs/TECHNICAL.md)** - Security architecture and implementation constraints
  311. - **[👨‍💻 Developer Reference](./docs/DEVELOPER.md)** - Contribution rules for tool and policy changes
  312. - **[📋 Documentation Index](./docs/INDEX.md)** - Complete documentation overview
  313. ## Features Highlights
  314. ### **🔄 Consolidation Achievements**
  315. ✅ **34→8 meta-tools** - Intelligent consolidation for better AI discovery
  316. ✅ **Multiple operations per tool** - Unified schemas with operation parameters
  317. ✅ **Smart parameter validation** - Clear error messages and type safety
  318. ### **🆕 Enhanced Data Capabilities**
  319. ✅ **Complete CRUD operations** - INSERT/UPDATE/DELETE/UPSERT with parameterized queries
  320. ✅ **Flexible querying** - SELECT with count/exists support and bounded safety limits
  321. ✅ **Arbitrary SQL execution** - Transaction support for complex operations
  322. ### **🔧 Production Ready**
  323. ✅ **Controlled connection** - CLI args or env vars by default; per-tool connection strings require opt-in
  324. ✅ **Security focused** - Read-only default mode, centralized policy checks, structured mutation predicates
  325. ✅ **Robust architecture** - Connection pooling, comprehensive error handling
  326. ## Docker Usage
  327. The PostgreSQL MCP Server is fully Docker-compatible and can be used in production environments. The image uses a multi-stage build, installs only production dependencies in the runtime stage, and runs as the non-root `node` user.
  328. ### Building the Image
  329. ```bash
  330. # Build locally
  331. docker build -t postgres-mcp-server .
  332. # Or pull from Docker Hub
  333. docker pull henkey/postgres-mcp:latest
  334. ```
  335. ### Running with Environment Variables
  336. ```bash
  337. # Basic usage (using Docker Hub image)
  338. docker run -i --rm \
  339. -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  340. henkey/postgres-mcp:latest
  341. # Or with locally built image
  342. docker run -i --rm \
  343. -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  344. postgres-mcp-server
  345. # With tools configuration
  346. docker run -i --rm \
  347. -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  348. -e POSTGRES_TOOLS_CONFIG="/app/config/tools.json" \
  349. -v /path/to/config:/app/config \
  350. postgres-mcp-server
  351. ```
  352. ### Docker Compose Example
  353. ```yaml
  354. version: '3.8'
  355. services:
  356. postgres-mcp:
  357. build: .
  358. environment:
  359. - POSTGRES_CONNECTION_STRING=postgresql://user:password@postgres:5432/database
  360. depends_on:
  361. - postgres
  362. stdin_open: true
  363. tty: true
  364. postgres:
  365. image: postgres:15
  366. environment:
  367. - POSTGRES_DB=database
  368. - POSTGRES_USER=user
  369. - POSTGRES_PASSWORD=password
  370. ports:
  371. - "5432:5432"
  372. ```
  373. ### MCP Client Configuration
  374. For use with MCP clients like Cursor or Claude Desktop:
  375. ```json
  376. {
  377. "mcpServers": {
  378. "postgresql-mcp": {
  379. "command": "docker",
  380. "args": [
  381. "run",
  382. "-i",
  383. "--rm",
  384. "-e",
  385. "POSTGRES_CONNECTION_STRING",
  386. "henkey/postgres-mcp:latest"
  387. ],
  388. "env": {
  389. "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
  390. }
  391. }
  392. }
  393. }
  394. ```
  395. ## Prerequisites
  396. - Node.js ≥ 18.0.0 (for local development)
  397. - Docker (for containerized deployment)
  398. - PostgreSQL server access
  399. - Valid connection credentials
  400. ## Contributing
  401. 1. Fork the repository
  402. 2. Create a feature branch
  403. 3. Commit your changes
  404. 4. Create a Pull Request
  405. See [Development Guide](./docs/DEVELOPMENT.md) for detailed setup instructions.
  406. ## License
  407. AGPLv3 License - see [LICENSE](./LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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