cruelkratos/dbms-mcp-server

db-mcp

A minimal Python MCP (Multi-Component Platform) server for managing and querying a PostgreSQL database. This project uses a repository pattern for database access and exposes endpoints for searching and adding records to a person table. Designed for integration with Claude MCP client.

This was mostly a fun side project made in a day not in any way a production ready MCP server, i wanted to see how i could use Copilot or Claude Desktop (or Cursor) like MCP Clients to actually interact and call tools (A simple POSTGRESQL call in this case), this was a fun learning expirience for me :)

Features

• PostgreSQL integration via environment variables
• Repository pattern for clean database logic
• MCP tool endpoints for search and add operations
• Simple configuration and test scripts

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL server running
• Claude MCP client (optional)

Installation

git clone https://github.com/cruelkratos/dbms-mcp-server.git
cd db-mcp
uv sync

Configuration

Create a .env file in the project root:

POSTGRES_DATABASE=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=yourpassword
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

Ensure your database has a table named person with columns: id, name, age, gender.

Ensure to update your MCP Client's JSON to connect to this MCP server (below is an example for claude desktop)

{
  "mcpServers": {
    "db_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "path\\to\\repo\\db_mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Running the Server

uv run main.py

Usage

Endpoints are exposed for:

• Looking up a person by name
• Looking up a person by ID
• Adding a new person

Interact using Claude MCP client or HTTP requests.

Example Screenshots

Project Structure

db_mcp/
├── main.py
├── repository.py
├── server.py
├── tools/
│   ├── controller.py
│   └── dbms.py
├── .env
├── test_db.py
├── test_dbms.py
├── test_mcp.py
└── README.md

Testing

python test_db.py
python test_dbms.py
python test_mcp.py

License

MIT License

Credits

MCP Documentation

Developed by cruelkratos😽