README

mcp-postgres

An MCP server that connects to a PostgreSQL database and exposes schema inspection and safe query execution as tools and resources — ready to plug into Claude Desktop or any MCP-compatible client.

Tools

Tool	Description
`list_tables`	List all tables in the public schema
`describe_table(table_name)`	Show columns, types, and nullability for a table
`run_query(query)`	Execute a SELECT query and return results (mutating statements are blocked)

Resources

URI	Description
`schema://tables`	Full schema dump — all tables with their columns

Setup

1. Clone and install

git clone <repo-url>
cd mcp-postgres
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

2. Configure environment

cp .env.example .env
# Edit .env — set DATABASE_URL to your PostgreSQL connection string

3. Run the server

mcp-postgres

Or directly:

python -m mcp_postgres.server

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "/path/to/.venv/bin/mcp-postgres",
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Project Structure

src/mcp_postgres/
  __init__.py   — package marker
  db.py         — psycopg2 connection context manager
  server.py     — FastMCP server, tools, and resources

Security

run_query rejects any statement that does not begin with SELECT. This prevents accidental or malicious data modification through the MCP interface.

mcp-postgres

README

mcp-postgres

Tools

Resources

Setup

1. Clone and install

2. Configure environment

3. Run the server

Claude Desktop Integration

Project Structure

Security

Recommended Servers