PostgreSQL MCP Full Access

A pure, full-access PostgreSQL MCP server for AI agents. Enables unrestricted SQL execution (DDL/DML) with zero database bundling.

This project embraces a "pure middleware" philosophy, stripping away restrictive database environment setups and hardcoded query filtering. It does exactly one thing: unconditionally accepts and executes any SQL command from your Agent (including CREATE, INSERT, UPDATE, DELETE, and DROP), and returns the result.

All connection methods, network architectures, and security constraints are entirely left to the user and the native PostgreSQL Role-Level Security (RLS) to manage.

✨ Key Features

• Network-First Microservice: Runs securely as an HTTP/SSE service within a closed Docker network, acting as a bridge between your AI Agent and Database without requiring risky host-level Docker socket mounts.
• Always Latest: No locked-in versions. Every build automatically pulls the latest Node.js, MCP SDK, and pg drivers, eliminating maintenance overhead.
• Unrestricted Access: Breaking free from the typical read-only sandbox. Your AI can autonomously create databases, define tables, and perform vector searches (e.g., pgvector).
• Dynamic Database Switching: Built-in support for switching databases mid-session—allowing the AI to create a new database and immediately connect to it to execute further commands.
• Clean Deployment: Easily configurable via docker-compose to run continuously in the background alongside your Agent.

---

🚀 Quick Start (Docker Network Mode)

1. Clone the repository

git clone https://github.com/BrassaiKao/postgresql-mcp-full-access.git
cd postgresql-mcp-full-access

2. Configure your Database URL Edit the docker-compose.yml file to include your target database connection string in the environment variables:

    environment:
      - DATABASE_URL=postgresql://agent_user:password@your_db_host:5432/postgres
      - PORT=7432

3. Build and Start the Service No local Node.js installation is required. Just run:

docker compose up -d --build

(This automatically pulls the latest dependencies and starts the MCP server in the background as a continuous service, listening on port 8000 within the Docker network.)

💡 Note on Docker Networking: By default, docker-compose.yml uses expose: "8000" to isolate traffic within the Docker network (hermes_net) for security. Docker Desktop will not show a published port mapping on your host OS.

If you need to access the SSE endpoint from your host machine (e.g., for local testing or Desktop apps), change expose: to ports: in docker-compose.yml:

ports:
  - "7432:7432"

⚙️ Usage with AI Agents

To use PostgreSQL MCP Full Access with an MCP-compatible agent (like Hermes Agent), you no longer need complex Docker subprocess commands. Just point your agent to the SSE endpoint in your agent's configuration file (e.g., ~/.hermes/config.yaml):

mcp_servers:
  postgres_middleware:
    url: "http://hermes_postgres_mcp:7432/sse"

(Ensure your Agent's container is on the same Docker network as this MCP service).

🛡️ Security Best Practices (Crucial)

1. Database Layer Isolation Because PostgreSQL MCP Full Access allows all SQL syntax, DO NOT give the AI your postgres (Superuser) credentials. Instead, create a dedicated Role in your PostgreSQL database. Use GRANT and REVOKE to precisely control which tables the Agent can read or write. By delegating security to the database layer, even if a Prompt Injection occurs, malicious commands will be natively blocked by PostgreSQL with a Permission denied error!

2. Network Layer Isolation Never expose the MCP server's port (7432) directly to the public internet or the host machine using -p 7432:7432 unless necessary. Rely on internal Docker networking to ensure only your AI Agent container can communicate with the MCP server.

🔍 Troubleshooting

1. Docker Permission Denied Error

If you encounter permission denied while trying to connect to the docker API at unix:///var/run/docker.sock during docker compose, your non-root user lacks access to the Docker daemon.

Fix this by adding your current user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

If you previously ran commands with sudo, take back ownership of your project directory:

sudo chown -R $USER:$USER .

2. Verify Container Logs

Check container logs to verify the server started correctly:

docker logs hermes_postgresql_mcp

Expected output: 🚀 Network MCP Server running! Agent can connect to http://localhost:7432/sse