home / mcp / postgresql mcp server

PostgreSQL MCP Server

Exposes PostgreSQL database operations as tools for AI assistants.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "guibracco-postgres-mcp-server": {
      "command": "poetry",
      "args": [
        "-C",
        "/absolute/path/to/postgres-mcp-server",
        "run",
        "python",
        "postgres-mcp-server/main.py"
      ]
    }
  }
}

You can use the PostgreSQL MCP Server to expose PostgreSQL database operations as tools for AI assistants. This server lets you run SQL queries and inspect your database schema through MCP-compatible clients, enabling automated workflows and robust data access for AI workflows.

How to use

You interact with the PostgreSQL MCP Server through an MCP client. First start the local server using the documented command, then connect your MCP client to the server to access tools such as retrieving the database schema. Use the get_schema tool to inspect the database structure, and issue SQL queries through the same tool interface your client provides. The server is designed to let AI assistants execute queries and examine table definitions, enabling data-driven conversations and automated data operations.

How to install

Prerequisites you need before installation:

Python 3.10 to 3.13 must be installed on your system.

Poetry is used for dependency management.

Follow these steps to install and configure the server:

# 1. Install Poetry (if needed)
curl -sSL https://install.python-poetry.org | python3 -
# Or follow the official installation method for your platform
```

```bash
# 2. Install project dependencies
poetry install
```

```bash
# 3. Prepare environment by copying the example env and configuring credentials
cp .env.example .env
```

```bash
# 4. Edit the .env file to include your PostgreSQL credentials
# Example values you should replace with real ones
DB_NAME=your_database
DB_USER=postgres
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
```

```bash
# 5. Run a quick local test (start server in the foreground)
poetry run python postgres-mcp-server/main.py
```

```bash
# 6. Optional: test using the Inspector (requires Node.js and npx)
# This opens a web UI to view tools and test get_schema
npx @modelcontextprotocol/inspector poetry run python postgres-mcp-server/main.py
```

```bash
# 7. If you want to test without the inspector, you can also run:
poetry run python postgres-mcp-server/main.py
```

Note: The Inspector allows you to view available tools, test get_schema, and observe real-time results. Press Ctrl+C to stop the server when you’re done.

Additional sections

Configuration and tools you will use are described below.

Available tools include get_schema() which retrieves the database schema.

Connection to the server can be configured through an MCP JSON snippet that you include in your client configuration. This example shows how to connect to the local MCP server using Poetry to launch the server process.

{
  "mcpServers": {
    "postgres": {
      "command": "poetry",
      "args": ["-C", "/absolute/path/to/postgres-mcp-server", "run", "python", "postgres-mcp-server/main.py"]
    }
  }
}
```

Replace `/absolute/path/to/postgres-mcp-server` with your actual project path. This configuration runs the server locally in a process managed by Poetry. The command and arguments are provided exactly as shown to ensure the server starts correctly in your environment.

Available tools

get_schema

Retrieve the database schema to understand table structures, columns, and relationships available in your PostgreSQL database.