Simple Psql MCP

🚀 Simple PostgreSQL MCP Server

This is a template project designed to assist those who wish to build their own MCP servers. I crafted it to be straightforward and easily adaptable—the code is very direct and comes with MCP documentation, so you can get started quickly.

🚀 Quick Start

This PostgreSQL MCP server provides an easy - to - use solution for interacting with databases using the MCP. Here's how you can get started:

Installation

1. Clone this repository.
2. Create and activate a virtual environment (recommended).
3. Run the following commands to install the dependencies:

pip install poetry
poetry install

Usage

1. Create an Example Database

To create an example PostgreSQL database with user and address tables, run the following script:

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

2. Run the Inspector Interface

To access the MCP server through the Inspector, run the following command:

npx @modelcontextprotocol/inspector uv --directory . run postgres

Then open http://localhost:3000/postgres in your browser.

✨ Features

This PostgreSQL MCP server implements the following:

Tools

• execute_query: Run SQL queries against the database.
• test_connection: Verify that the database connection is working properly.

Resources

• db://tables: List all tables in the schema.
• db://tables/{table_name}: Schema information for a specific table.
• db://: Pre - loaded prompt templates that allow users to query the database directly using an LLM.

Prompts

• Pre - loaded prompt templates that enable users to query the database directly with an LLM.

📦 Installation

1. Clone this repository.
2. Create and activate a virtual environment (recommended).
3. Run the following commands to install the dependencies:

pip install poetry
poetry install

💻 Usage Examples

Basic Usage

To create an example database:

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

Advanced Usage

To run the Inspector interface and access the MCP server:

npx @modelcontextprotocol/inspector uv --directory . run postgres

Then open http://localhost:3000/postgres in your browser.

📚 Documentation

• It includes easy - to - understand MCP documentation for LLM development.
• Based on the approach here.

🔧 Technical Details

The Model Context Protocol (MCP) is a standard way for LLMs to interact with external tools and data. In a nutshell:

• Tools allow LLMs to execute commands (e.g., run database queries).
• Resources are data that can be attached to a conversation (e.g., attaching a file to a prompt).
• Prompts are consistent LLM instruction templates.

📄 License

MIT

🔧 Extending the Project

To extend this project and add a new MCP server:

1. Create a new sub - directory under the /src directory (e.g., /src/my - new - mcp).
2. Implement your new MCP server based on the PostgreSQL example.
3. Add the new MCP to pyproject.toml:

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

Then you can run the new MCP:

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

⚠️ Important Note

This is an experimental project aimed at empowering developers to build their own MCP servers. I've tried to ensure it doesn't crash immediately, but be careful—it's very easy to run SQL injections. In short, don't use it in a production environment unless you're the founder of a startup with no paying customers.