home / mcp / postgresql mcp server
Provides safe, structured access to PostgreSQL databases for AI assistants with CRUD, queries, and schema discovery.
Configuration
View docs{
"mcpServers": {
"cesarvarela-postgres-mcp": {
"command": "node",
"args": [
"/path/to/postgres-mcp/dist/index.js"
],
"env": {
"DATABASE_URL": "postgresql://username:password@localhost:5432/database_name"
}
}
}
}You use the PostgreSQL MCP Server to give AI assistants secure, structured access to your PostgreSQL databases. It exposes a set of safe, parameterized data operations, schema discovery, and robust error handling so you can integrate database capabilities into conversational or autonomous AI workflows without risk of injection or unsafe actions.
Connect your MCP client to the PostgreSQL MCP Server and start issuing tools to query, inspect, insert, update, or delete data. You can retrieve detailed table schemas, execute parameterized queries safely, and perform CRUD operations with safeguards such as required WHERE clauses for updates and deletes, plus optional confirmations for large operations. Use the tooling to explore database structures, filter and paginate results, and get immediate feedback on operation results with structured returning columns.
Prerequisites you need before running the server:
1. Node.js is installed on your machine.
2. npm is available to install project dependencies.
3. A PostgreSQL database is reachable with a connection string you can store in an environment file.
Step-by-step commands you will run to set up and start the MCP server:
npm installnpm install
# Prepare environment file with your database connection details
cp .env.example .env
# Edit .env to set DATABASE_URL and any optional settings
# Example:
# DATABASE_URL=postgresql://username:password@localhost:5432/database_name
# Start in development mode (if available)
npm run dev
# Or build and run the built version
npm run build
node dist/index.jsConfiguration is driven by environment variables. The recommended variable is DATABASE_URL, which should contain your PostgreSQL connection string. You can control environment and debugging with NODE_ENV and DEBUG, and you may adjust connection pool settings like MAX_CONNECTIONS and QUERY_TIMEOUT.
To keep your data safe, the server uses parameterized queries for all SQL operations, validates identifiers against PostgreSQL naming rules, and requires a WHERE clause for UPDATE and DELETE actions. Large operations can require explicit confirmation, and you should enforce SSL connections in production. Set appropriate database-level permissions to restrict what the MCP server can do.
Grant the minimum necessary permissions for the user that the MCP server uses. For read-only access, grant SELECT on all tables in the public schema. For full access, grant SELECT, INSERT, UPDATE, DELETE on all tables in the public schema. Also grant usage or selective SELECT on information_schema as needed for introspection.
Once connected through an MCP client, you can perform these core actions by selecting the appropriate tools in your client interface:
Testing is performed with Vitest and testcontainers against real PostgreSQL databases. Run the test suite to verify behavior in your environment.
Query data from a specific table with filtering, pagination, and sorting. Parameters: table, columns, where, pagination, sort.
Get database schema information including tables, columns, and constraints. Parameters: schema_name, table_pattern, include_columns, include_constraints.
Execute a parameterized SQL query with safety checks. Parameters: query, params, explain.
Insert new records into a table. Parameters: table, data, on_conflict, conflict_columns, returning.
Update existing records with safety. Parameters: table, data, where, returning.
Delete records with safety. Parameters: table, where, confirm_delete, returning.
Get detailed information about a specific table. Parameters: table, schema_name, include_statistics.
Check database connection status and retry if needed. Parameters: retry.