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.

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

Variable	Required	Default	Description
DATABASE_URL	yes	—	PostgreSQL connection string
SEMANTIC_FILE	no	—	Path to your semantic layer markdown
LLM_BASE_URL	no	https://api.openai.com/v1	OpenAI-compatible endpoint
LLM_API_KEY	no	—	Required for search_schema
LLM_MODEL	no	gpt-4o-mini	LLM model name
CACHE_REFRESH_MINUTES	no	30	Background cache refresh interval
CACHE_SCHEMAS	no	all	Comma-separated schema names to cache
SAMPLE_DATA_LIMIT	no	5	Default row count for sample_data

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