Supabase MCP Server: Tables, Queries, Edge Functions

Overview

The Supabase MCP Server implements a Model Context Protocol (MCP) back-end on top of Supabase (Postgres + Realtime + Edge Functions). It exposes a minimal set of HTTP endpoints and utilities to create/manage tables, run SQL/parameterized queries, and deploy server-side Edge Functions that provide scalable, low-latency context for LLMs or other model-driven applications.

This server is designed for developers who need a persistent, queryable context layer for stateful AI applications, chat history, personalization, or analytics. By combining Supabase storage and real-time features with MCP-style APIs and edge functions, this project makes it straightforward to store contextual data, retrieve it with controlled queries, and run bespoke logic at the edge.

Features

• Create and manage Postgres tables via a small HTTP API
• Run parameterized and raw SQL queries programmatically
• Deploy and invoke Edge Functions for server-side logic and model orchestration
• Support for real-time updates through Supabase Realtime (WebSocket)
• Simple authentication via Supabase service key or JWTs
• Local development and Docker-ready deployment patterns

Installation / Configuration

1. Clone the repository

git clone https://github.com/supabase-community/supabase-mcp.git
cd supabase-mcp

2. Create a .env file (example)

# .env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
PORT=3000
NODE_ENV=development

3. Install dependencies (Node example)

npm install
# or
yarn install

4. Run locally

# Start the MCP server
npm run dev
# or with Node directly
node src/server.js

5. Docker (optional) — example docker-compose snippet

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_SERVICE_KEY=${SUPABASE_SERVICE_KEY}

6. Deploy Edge Functions with the Supabase CLI

# install supabase cli if needed
supabase login
supabase init
# deploy an edge function folder named 'mcp-handler'
supabase functions deploy mcp-handler --project-ref your-project-ref

Available Resources

• GitHub repository: https://github.com/supabase-community/supabase-mcp
• Supabase docs (for configuring Postgres, auth, and edge functions): https://supabase.com/docs
• MCP-style endpoints exposed by the server (typical paths)

(Exact endpoint paths may vary by release — check the repo README for the current API surface.)

Examples

Create a table (API)

curl -X POST https://localhost:3000/tables \
  -H "Authorization: Bearer ${SUPABASE_SERVICE_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "chat_history",
    "columns": [
      {"name": "id", "type": "uuid", "primary": true, "default": "gen_random_uuid()"},
      {"name": "user_id", "type": "text"},
      {"name": "message", "type": "text"},
      {"name": "created_at", "type": "timestamptz", "default": "now()"}
    ]
  }'

Run a parameterized query

curl -X POST https://localhost:3000/queries \
  -H "Authorization: Bearer ${SUPABASE_SERVICE_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM chat_history WHERE user_id = $1 ORDER BY created_at DESC LIMIT $2",
    "params": ["user_123", 10]
  }'

Invoke an edge function

curl -X POST https://your-project.supabase.co/functions/v1/mcp-handler \
  -H "Authorization: Bearer ${SUPABASE_SERVICE_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"action":"summarize","conversation_id":"conv_789"}'

Use Cases

• Chatbots and conversational AI: Store user messages, system prompts, and model outputs in a table; query recent turns as model context before each completion.
• Personalization: Keep user preferences and interaction events in a queryable store; run edge functions to compute features or transforms for model inputs.
• Analytics and telemetry: Log events, run aggregated queries for dashboards, and push real-time changes to front-end via Supabase Realtime.
• Moderation and filtering pipelines: Use edge functions to apply policy checks to incoming messages or content before persisting or forwarding to a model.

Concrete example — session context for a chat app:

1. Create a chat_history table (as shown above).
2. On each user message, insert a row via /queries or direct Postgres insert.
3. Before calling the LLM, run a /queries call to fetch the last N messages for that user and pass them to the model.
4. Optionally, run an edge function to sanitize or enrich messages (e.g., embedding, metadata extraction) before storage.

Best Practices and Notes

• Use a Supabase service role key on trusted backends only; never expose it to client-side code.
• Prefer parameterized queries to avoid SQL injection when executing dynamic SQL.
• Use edge functions for CPU- or policy-sensitive logic rather than embedding heavy logic in the MCP server process.
• Monitor your Supabase Postgres limits and plan for indexing hot tables (e.g., chat history by user_id + created_at).

For more details, configuration options, and the exact API schema, see the project repository: https://github.com/supabase-community/supabase-mcp