Postgresql Alchemy

🚀 Talk to Your Database with MCP

This project enables you to interact with your database using MCP. It provides a way to communicate with a PostgreSQL database via Claude Desktop, and it should also work with MySQL, MariaDB, and SQLite as it uses sqlalchemy under the hood. The project is built upon https://github.com/runekaagaard/mcp-alchemy.

⚠️ Important Note

This guide assumes you have a basic understanding of Docker, environment variables, and CLI usage.

🚀 Quick Start

✅ Prerequisites

• Docker Compose: Installation instructions
• Claude Desktop: Download here
• uv: A modern, high-performance Python package manager. If not installed, follow the instructions below.

🔧 Step 1: Set Up Environment Variables

1. Copy and rename the environment file
   Copy the provided .env.example file and rename it to .env:

   cp .env.example .env
   

🔧 Step 2: Set Up Claude Desktop

1. Download and install Claude Desktop
   Visit the Claude Desktop download page and install the application.

🔧 Step 3: Start the PostgreSQL Database with Dummy Data

1. Run Docker Compose
   Ensure Docker Compose is installed and run the following command:

   docker-compose up -d
   

   • This command will start a PostgreSQL database at localhost:5432 and populate it with dummy data.

🔧 Step 4: Install uv (if not installed)

1. Install uv
   Execute the following command to install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

🔧 Step 5: Configure and Start the MCP Server

1. Create/Update MCP Server Configuration
   Save the following JSON configuration to your MCP server configuration file (adjust the path as needed):

   {
     "mcpServers": {
       "my_database": {
         "command": "uv",
         "args": [
           "--directory",
           "/directory/where/this/app/is/located/app/",
           "run",
           "server.py"
         ],
         "env": {
           "DB_URL": "postgresql://postgres:password@localhost:5432/mydatabase"
         }
       }
     }
   }
   

   💡 Usage Tip

   If uv is installed in a non-standard location, update the "command" value to reflect the full path of the executable.

2. Start the MCP Server
   After the configuration is ready, the MCP server will start automatically every time you launch Claude Desktop.

🔧 Step 6: Enjoy Your Setup

• Open Claude Desktop.
• The tool will automatically call your MCP server, allowing you to interact with the database seamlessly.

📚 Summary

1. Set up environment variables: Copy .env.example to .env.
2. Install and run Claude Desktop: Download from Claude Desktop.
3. Start PostgreSQL with Docker Compose: Run docker-compose up to start the database with dummy data.
4. Install uv: Run the provided installation command if necessary.
5. Configure the MCP server: Update the configuration file and ensure the paths and environment variables are correct.
6. Start and have fun: Launch Claude Desktop to start interacting with your database via MCP.

If you encounter any issues or need further assistance, please refer to the relevant documentation or contact the support team.

Happy coding!