Runs as a Node.js application, serving as the execution environment for the MCP server
Provides a secure read-only interface to PostgreSQL databases, allowing execution of validated SELECT queries with timeout protection
MCP Postgres Query Server
A Model Context Protocol (MCP) server implementation for querying a PostgreSQL database in read-only mode, designed to work with Claude Desktop and other MCP clients.
Overview
This project implements a Model Context Protocol (MCP) server that provides:
A secure, read-only interface to a PostgreSQL database
Integration with Claude Desktop through the MCP protocol
SQL query validation to ensure only SELECT queries are executed
Query timeout protection (10 seconds)
Prerequisites
Node.js (v14 or later)
npm (comes with Node.js)
PostgreSQL database (connection details provided via command line)
Installation
Connecting to Claude Desktop
You can configure Claude Desktop to automatically launch and connect to the MCP server:
Access the Claude Desktop configuration file:
Open Claude Desktop
Go to Settings > Developer > Edit Config
This will open the configuration file in your default text editor
Add the postgres-query-server to the
mcpServers
section of yourclaude_desktop_config.json
:
Replace
/path/to/your/
with the actual path to your project directory.Replace the PostgreSQL connection string with your actual database credentials.
Save the file and restart Claude Desktop. The MCP server should now appear in the MCP server selection dropdown in Settings.
Example Configuration
Here's a complete example of a configuration file with postgres-query:
Updating Configuration
To update your Claude Desktop configuration:
Open Claude Desktop
Go to Settings > Developer > Edit Config
Make your changes to the configuration file
Save the file
Restart Claude Desktop for the changes to take effect
If you've updated the MCP server code, make sure to rebuild it with
npm run build
before restarting
Features
Read-Only Database Access: Only SELECT queries are permitted for security
Query Validation: Prevents potentially harmful SQL operations
Timeout Protection: Queries running longer than 10 seconds are automatically terminated
MCP Protocol Support: Complete implementation of the Model Context Protocol
JSON Response Formatting: Query results are returned in structured JSON format
API
Tools
query-postgres
Executes a read-only SQL query against the configured PostgreSQL database.
Parameters:
query
(string): A SQL SELECT query to execute
Response:
JSON object containing:
rows
: The result set rowsrowCount
: Number of rows returnedfields
: Column metadata
Example:
Development
The main server implementation is in src/index.ts
. Key components:
PostgreSQL connection pool setup
Query validation logic
MCP server configuration
Tool and resource definitions
To modify the server's behavior, you can:
Edit the query validation logic in
isReadOnlyQuery()
Add additional tools or resources to the MCP server
Modify the query timeout duration (currently 10 seconds)
Security Considerations
The server validates all queries to ensure they are read-only
Connection to the database uses SSL
Query timeout prevents resource exhaustion
No write operations are permitted
Database credentials are passed directly via command line arguments, not stored in files
License
ISC
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A secure Model Context Protocol server that allows Claude to execute read-only SQL queries against a PostgreSQL database, enabling natural language interaction with database data.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that enables Claude to execute SQL queries on Snowflake databases with automatic connection lifecycle management.Last updated -43MIT License
- -securityFlicense-qualityA Model Context Protocol server that provides read-only access to PostgreSQL databases, enabling LLMs to inspect database schemas and execute read-only queries.Last updated -21,552
- -securityFlicense-qualityA Model Context Protocol server that allows Large Language Models like Claude to execute SQL queries, explore database schemas, and maintain persistent connections to SQL Server databases.Last updated -
- AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude to access and interact with Oracle databases through natural language queries.Last updated -3MIT License