Simple PostgreSQL MCP Server

What is Simple PostgreSQL MCP Server?

It is a template project for developers wanting to build their own MCP servers, designed to be dead simple to understand and adapt. It implements a PostgreSQL MCP server that provides tools, resources, and prompts, allowing LLMs to interact with a PostgreSQL database through natural language queries.

How to use Simple PostgreSQL MCP Server?

Prerequisites: Python 3.8+, uv, npx, and a PostgreSQL database. Set up a virtual environment, install dependencies, then run the server with the MCP Inspector using npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=... -e SCHEMA=public. Alternatively, configure an AI assistant (e.g., Claude Desktop) with a JSON configuration file, or use the included generate_mcp_config.sh script. Once connected, ask the LLM questions in natural language about your data.

Key features of Simple PostgreSQL MCP Server

• execute_query tool – run SQL queries against the database
• test_connection tool – verify the database connection
• Resources: db://tables, db://tables/{table_name}, db://schema
• Prompts for query generation and analytical query building
• Template structure for extending with custom MCP servers

Use cases of Simple PostgreSQL MCP Server

• Query database tables and schema using natural language
• Test database connectivity interactively
• Explore schema information without writing raw SQL
• Build and test custom MCP servers by following the template

FAQ from Simple PostgreSQL MCP Server

What prerequisites are needed?

Python 3.8+, uv (modern Python package manager), npx (included with Node.js), and a PostgreSQL database you can connect to.

How do I connect to my database?

Set the DSN (e.g., postgresql://username:password@hostname:port/database) and SCHEMA environment variables when running the inspector or in the MCP configuration file.

Is there an example database I can use?

Yes. Run the included script ./example-db/create-db.sh to create a Docker container with a PostgreSQL database pre-populated with sample users and addresses tables.

Can I extend this server for other services?

Yes. Create a new directory under /src, implement your MCP server following the PostgreSQL example, and add your entry point to pyproject.toml. Then run it with npx @modelcontextprotocol/inspector uv --directory . run your-mcp-name.

Is this production-ready?

No. This is an experimental project; it only checks that the query starts with SELECT, making SQL injections easy. Do not run in production unless you are the founder and there are no paying clients.