README.md

@supabase/mcp-server-postgrest

This is an MCP server for PostgREST. It allows LLMs perform database queries and operations on Postgres databases via PostgREST.

This server works with both Supabase projects (which use PostgREST) and standalone PostgREST servers.

Tools

The following tools are available:

postgrestRequest

Performs an HTTP request to a configured PostgREST server. It accepts the following arguments:

• method: The HTTP method to use (eg. GET, POST, PATCH, DELETE)
• path: The path to query (eg. /todos?id=eq.1)
• body: The request body (for POST and PATCH requests)

It returns the JSON response from the PostgREST server, including selected rows for GET requests and updated rows for POST and PATCH requests.

sqlToRest

Converts a SQL query to the equivalent PostgREST syntax (as method and path). Useful for complex queries that LLMs would otherwise struggle to convert to valid PostgREST syntax.

Note that PostgREST only supports a subset of SQL, so not all queries will convert. See sql-to-rest for more details.

It accepts the following arguments:

• sql: The SQL query to convert.

It returns an object containing method and path properties for the request. LLMs can then use the postgrestRequest tool to execute the request.

Usage

With Claude Desktop

Claude Desktop is a popular LLM client that supports the Model Context Protocol. You can connect your PostgREST server to Claude Desktop to query your database via natural language commands.

You can add MCP servers to Claude Desktop via its config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows:%APPDATA%\Claude\claude_desktop_config.json

To add your Supabase project (or any PostgREST server) to Claude Desktop, add the following configuration to the servers array in the config file:

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

Configuration

• apiUrl: The base URL of your PostgREST endpoint

• apiKey: Your API key for authentication (optional)

• schema: The Postgres schema to serve the API from (eg. public). Note any non-public schemas must be manually exposed from PostgREST.

Programmatically (custom MCP client)

If you're building your own MCP client, you can connect to a PostgREST server programmatically using your preferred transport. The MCP SDK offers built-in stdio and SSE transports. We also offer a StreamTransport if you wish to directly connect to MCP servers in-memory or by piping over your own stream-based transport.

Installation

npm i @supabase/mcp-server-postgrest

yarn add @supabase/mcp-server-postgrest

pnpm add @supabase/mcp-server-postgrest

Example

The following example uses the StreamTransport to connect directly between an MCP client and server.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamTransport } from '@supabase/mcp-utils';
import { PostgrestMcpServer } from '@supabase/mcp-server-postgrest';

// Create a stream transport for both client and server
const clientTransport = new StreamTransport();
const serverTransport = new StreamTransport();

// Connect the streams together
clientTransport.readable.pipeTo(serverTransport.writable);
serverTransport.readable.pipeTo(clientTransport.writable);

const client = new Client(
  {
    name: 'MyClient',
    version: '0.1.0',
  },
  {
    capabilities: {},
  }
);

const supabaseUrl = 'https://your-project-ref.supabase.co'; // http://127.0.0.1:54321 for local
const apiKey = 'your-anon-key'; // or service role, or user JWT
const schema = 'public'; // or any other exposed schema

const server = new PostgrestMcpServer({
  apiUrl: `${supabaseUrl}/rest/v1`,
  apiKey,
  schema,
});

// Connect the client and server to their respective transports
await server.connect(serverTransport);
await client.connect(clientTransport);

// Call tools, etc
const output = await client.callTool({
  name: 'postgrestRequest',
  arguments: {
    method: 'GET',
    path: '/todos',
  },
});