Pgmcp

Overview

PGMCP connects the pgkeen Postgres Docker image to a mesh-based FastMCP-backed server. It bridges AI Agents with low-level PostgreSQL administration, asynchronous crawling, knowledge base ingestion/curation/search, and more.

Servers

PGMCP Server (server.py)

The main FastMCP server that acts as the hub for all sub-servers listed below. It provides a unified interface interacting with each sub-server and focuses on routing and tool composition. Each of the sub-servers are mounted onto this server.

Knowledge Base Server (server_kb.py)

A concise interface for ingesting, curating, and semantically searching technical documentation and web content across multiple corpora. Features include corpus discovery, ingestion pipelines, document chunking, embedding, and RAG-based retrieval.

crawl_to_kbase.webm

Crawl Server (server_crawl.py)

These tools offer a unified interface for AI Agents to orchestrate, monitor, and analyze web crawling jobs with Scrapy and PostgreSQL. They support the full job lifecycle as well as metadata and log management.

Scrapy's configuration is flexible and will eventually be exposable. Currently, sensible defaults are set for local crawling. The crawl toolset streamlines job management and provides detailed insights into job execution and results.

PSQL Server (server_psql.py)

This server provides a set of tools for low-level PostgreSQL administration, including executing SQL queries, managing extensions, and handling functions. It is designed to be used by AI Agents for advanced database management tasks.

[!NOTE] Basic enforcement of SQL query type safety is provided, but it is recommended to use these tools with caution, and never in production environments.

Server Setup

1. Clone the repository:

   git clone <repository-url> /your/local/path/to/pgmcp
   

2. Navigate to the project directory:

   cd /your/local/path/to/pgmcp
   

3. Install the required dependencies:

   uv sync
   

4. Run the server:

   uv run pgmcp run --port 8000 --transport streamable-http
   

   You should see something like this:

   [07/30/25 14:32:54] INFO     Starting MCP server 'pgmcp' with transport 'streamable-http' on http://0.0.0.0:8000/mcp/
   INFO:     Started server process [13951]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
   

Client Setup

VSCode

1. Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P).
2. Select MCP: Add Server...
3. Choose "HTTP" option.
4. Enter the server URL (e.g., http://localhost:8000/mcp/).
5. Enter a "server id" (e.g., pgmcp).
6. Select Global for the scope.
7. Done. (It should appear in the extensions sidebar.)

Roo / Cline / Claude

{
  "mcpServers": {
    "pgmcp": {
      "url": "http://localhost:7999/mcp/",
      "type": "streamable-http",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}