This MCP server provides read-only access to PostgreSQL databases via the MCP (Model Context Protocol). It supports dynamic database connections at request time, ensuring credentials are not hardcoded. The server exposes MCP tools for listing schemas and tables, performing read-only selects, and executing safe read-only queries. To start, run the server (e.g., via a built JAR) and connect with an MCP client by referencing the available tool names such as list_schemas, list_tables, select, and execute_query. A typical workflow is to point the client at a running instance on port 3000, provide the necessary connection parameters (host, database, username, password), and then invoke the desired tool with the appropriate arguments. The server enforces read-only operations, validating inputs and restricting queries to SELECT-like statements to maintain database safety.

Prerequisites:

• Java 21
• Maven 3.9+ (for build)
• Docker and Docker Compose (optional, for testing with sample data)

Install and run:

1. Clone the repository: git clone https://github.com/luanvuhlu/mcp-server-postgres.git cd mcp-server-postgres

2. Build the project: mvn clean package

3. Run the server locally: mvn spring-boot:run

   or run the packaged JAR directly after packaging:

   java -jar target/mcp-server-postgres-1.0.0-SNAPSHOT.jar

4. Optional: test with Docker Compose (provided in the repo) to set up a sample PostgreSQL database: docker-compose up -d

5. If using Docker, you can build an image and run: docker build -t mcp-server-postgres . docker run -p 3000:3000 mcp-server-postgres

Notes and tips:

• The server is designed for read-only access; allowed queries are restricted to SELECT, WITH, SHOW, EXPLAIN, DESCRIBE as part of the MCP safety rules.
• All database connections are provided dynamically per-request; there are no default credentials stored in the server.
• The MCP protocol is JSON-RPC over stdio or TCP. Clients communicate via the defined tools: list_schemas, list_tables, select, and execute_query.
• In a production setting, consider exposing port 3000 through a reverse proxy and securing MCP traffic.
• If you customize application properties, you can adjust the MCP server port under spring.ai.mcp.server.port (default shown as 3000 in docs).
• For development, tests and sample data are available via the provided Docker Compose setup; it includes a PostgreSQL instance with sample schemas and tables.