Supabase Postgrest MCP Server

Overview

Supabase Postgrest MCP Server is a specialized Model Context Protocol (MCP) server developed by the Supabase community. It bridges large language models (LLMs) with PostgreSQL databases through PostgREST, a web server that automatically converts PostgreSQL database schemas into RESTful APIs. The server enables seamless interaction with both Supabase-hosted PostgreSQL instances and standalone PostgREST implementations.

This MCP server translates natural language instructions from LLMs into structured queries and operations that can be executed against PostgreSQL databases. By leveraging PostgREST's RESTful interface, it eliminates the need for direct database connections while maintaining robust data access capabilities.

Features

PostgREST Integration

• Direct connection to PostgREST endpoints
• Support for all standard HTTP methods (GET, POST, PATCH, DELETE)
• Authentication via API keys
• Schema-aware operations

SQL Translation

• Converts SQL queries to PostgREST syntax automatically
• Handles complex query patterns
• Provides method and path information for RESTful requests

Flexible Configuration

• Works with both Supabase and standalone PostgREST servers
• Schema selection capabilities
• Environment-specific settings

Transport Options

• Support for multiple transport protocols
• Compatible with stdio for Claude Desktop
• Works with custom stream-based transports
• SSE support for web applications

Use case

The Supabase Postgrest MCP server excels in scenarios where AI assistants need to interact with PostgreSQL databases directly:

• Data Analysis Projects: LLMs can fetch, analyze, and visualize database content through natural language requests
• Database Administration: Execute maintenance and exploratory operations without writing raw SQL
• Application Development: Allow AI tools like Claude or Cursor to manipulate database structures and content during development
• Data-driven Chatbots: Create conversational interfaces that can read from and write to PostgreSQL databases
• Automated Reporting: Generate reports by querying databases based on user requests
• Data Validation: Verify data integrity with complex constraint checks

Tools

postgrestRequest

Performs HTTP requests to a configured PostgREST server with the following parameters:

• method: HTTP method (GET, POST, PATCH, DELETE)
• path: Resource path with query parameters
• body: Request body for POST/PATCH requests

Returns JSON responses containing queried or modified data.

sqlToRest

Converts SQL statements to equivalent PostgREST syntax with parameters:

• sql: The SQL query to convert

Returns an object with method and path properties that can be used with the postgrestRequest tool.

Integration complexity

Rating: 3/5

The integration requires moderate technical knowledge including:

• Understanding of PostgreSQL and PostgREST
• Familiarity with API authentication
• Basic command-line operations
• Configuration of MCP clients

However, comprehensive documentation and examples significantly reduce complexity.

Setup Guide

Claude Desktop Setup

1. Locate your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the following configuration to the mcpServers object:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-postgrest",
        "--apiUrl",
        "https://your-project-ref.supabase.co/rest/v1",
        "--apiKey",
        "your-anon-key",
        "--schema",
        "public"
      ]
    }
  }
}

3. Replace the placeholder values:
   • your-project-ref with your Supabase project reference
   • your-anon-key with your Supabase anon key
   • Adjust schema if using a non-public schema
4. Restart Claude Desktop to apply changes

Cursor Setup

1. Open or create the .cursor/mcp.json file in your project directory
2. Add the MCP server configuration:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y", 
        "@supabase/mcp-server-postgrest",
        "--apiUrl", 
        "https://your-project-ref.supabase.co/rest/v1",
        "--apiKey", 
        "your-anon-key",
        "--schema", 
        "public"
      ]
    }
  }
}

3. Replace the placeholder values as needed
4. Restart Cursor or reload the MCP configuration

Programmatic Setup (Custom MCP Client)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamTransport } from '@supabase/mcp-utils';
import { PostgrestMcpServer } from '@supabase/mcp-server-postgrest';
 
// Create transports
const clientTransport = new StreamTransport();
const serverTransport = new StreamTransport();
 
// Connect streams
clientTransport.readable.pipeTo(serverTransport.writable);
serverTransport.readable.pipeTo(clientTransport.writable);
 
// Initialize client
const client = new Client(
  { name: 'MyClient', version: '0.1.0' },
  { capabilities: {} }
);
 
// Configure server
const server = new PostgrestMcpServer({
  apiUrl: 'https://your-project-ref.supabase.co/rest/v1',
  apiKey: 'your-anon-key',
  schema: 'public',
});
 
// Connect client and server
await server.connect(serverTransport);
await client.connect(clientTransport);
 
// Example tool call
const output = await client.callTool({
  name: 'postgrestRequest',
  arguments: {
    method: 'GET',
    path: '/todos',
  },
});