pg-semantic-mcp

A PostgreSQL MCP server for AI coding agents.

Exposes your database schema — table names, column types, comments, and sample data — as MCP tools. Includes semantic search powered by any OpenAI-compatible LLM, enriched by a user-authored semantic layer document.

Features

• list_tables — discover all tables with comments

• describe_table — inspect column names, types, nullability, and comments

• sample_data — fetch example rows from any table

• search_schema — keyword search across tables and columns using LLM + your semantic context

No SQL execution. Read-only. No vector database required.

Related MCP server: dbecho

Install

pip install pg-semantic-mcp

Requires Python 3.11+ and a running PostgreSQL instance.

Quick Start

export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
export LLM_API_KEY="sk-..."          # required only for search_schema
pg-semantic-mcp

Configuration

You can also use a .env file in the working directory.

Register with OpenCode

Add to your opencode.json:

{
  "mcp": {
    "pg-data": {
      "type": "local",
      "command": "pg-semantic-mcp",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname",
        "SEMANTIC_FILE": "/path/to/SCHEMA.md",
        "LLM_API_KEY": "sk-..."
      }
    }
  }
}

The same config works for Claude Code, Cursor, and any other MCP-compatible agent.

Semantic Layer

Create a SCHEMA.md file describing your database — naming conventions, business term mappings, design decisions. See SCHEMA.md.example for a template.

This document is loaded at startup and included in the search_schema LLM prompt. It is the main way to teach the agent about your specific domain.

Compatible LLMs

search_schema calls any OpenAI-compatible endpoint:

• OpenAI (gpt-4o-mini, gpt-4o, ...)

• DeepSeek (deepseek-v4, set LLM_BASE_URL=https://api.deepseek.com/v1)

• Anthropic via proxy

• Local models via Ollama or LM Studio

License

MIT