How to Set Up Supabase MCP Server (2026)

How to Set Up Supabase MCP Server in 2026

Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources. The Supabase MCP server gives AI tools like Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP-compatible clients direct access to your Supabase project -- including database queries, table management, edge functions, and storage.

This means your AI assistant can query your production data, create tables, run migrations, manage RLS policies, and debug issues without you manually copying SQL back and forth.

What Is MCP?

MCP (Model Context Protocol) was created by Anthropic as a standardized way for AI models to interact with external systems. Think of it as a universal plugin system for AI assistants.

How it works:

AI Assistant <---> MCP Client <---> MCP Server <---> Supabase
(Claude, etc.)   (built-in)     (you configure)   (your project)

The MCP server exposes "tools" that the AI can call. For Supabase, these tools include running SQL queries, listing tables, managing storage buckets, and more.

Prerequisites

Before setting up the Supabase MCP server, you need:

• A Supabase project (free tier works)
• An MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, etc.)
• Node.js 18+ installed
• Your Supabase project URL and service role key

Get your Supabase credentials:

1. Go to your Supabase Dashboard.
2. Select your project.
3. Navigate to Settings > API.
4. Copy your Project URL (e.g., https://abcdefg.supabase.co).
5. Copy your service_role key (not the anon key -- MCP needs elevated access).

Method 1: Official Supabase MCP Server

Supabase provides an official MCP server package that works with all major MCP clients.

Setting Up with Claude Desktop

Step 1: Install the MCP server

The Supabase MCP server runs via npx, so you do not need to install it globally. You configure it in your Claude Desktop settings.

Step 2: Configure Claude Desktop

Open the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the Supabase MCP server configuration:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. You should see the Supabase tools available in the tools menu (the hammer icon).

Setting Up with Claude Code

For Claude Code (the terminal-based CLI), add the MCP server to your project configuration:

# Add the Supabase MCP server to your project
claude mcp add supabase \
  --command "npx -y @supabase/mcp-server-supabase@latest \
  --supabase-url https://your-project-id.supabase.co \
  --supabase-service-role-key your-service-role-key-here"

Or add it manually to your .claude/mcp.json file:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

Setting Up with Cursor

In Cursor, open Settings > MCP and add a new server:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://your-project-id.supabase.co",
        "--supabase-service-role-key",
        "your-service-role-key-here"
      ]
    }
  }
}

Available MCP Tools

Once connected, your AI assistant has access to these tools:

Tool	Description	Example Use
list_tables	List all tables in the database	"Show me all tables in my project"
execute_sql	Run any SQL query	"Query all users who signed up this week"
get_table_schema	Get column info for a table	"What columns does the orders table have?"
create_table	Create a new table	"Create a products table with name, price, and SKU"
insert_rows	Insert data into a table	"Add 5 sample products to the products table"
update_rows	Update existing rows	"Set all inactive users' status to archived"
delete_rows	Delete rows from a table	"Remove all test data from the orders table"
list_storage_buckets	List storage buckets	"Show me all storage buckets"
list_edge_functions	List edge functions	"What edge functions are deployed?"
get_project_info	Get project metadata	"Show me my project's configuration"
apply_migration	Apply a SQL migration	"Create a migration to add an email index"
list_rls_policies	List RLS policies	"What security policies are on the profiles table?"

Practical Examples

Example 1: Exploring Your Database

Once connected, simply ask your AI assistant natural language questions:

You: What tables do I have in my Supabase project?

AI: Let me check your database schema.
[Calls list_tables]

You have 6 tables:
- users (1,247 rows) - User accounts
- profiles (1,245 rows) - User profile information
- orders (3,892 rows) - Purchase orders
- products (156 rows) - Product catalog
- order_items (8,431 rows) - Individual items in orders
- categories (12 rows) - Product categories

Example 2: Writing and Running Queries

You: Show me the top 10 customers by total order value this month.

AI: I'll query the database for you.
[Calls execute_sql]

Here are the top 10 customers by order value in February 2026:

| Rank | Customer | Email | Total Spent |
|------|----------|-------|------------|
| 1 | Jane Smith | jane@... | $2,450.00 |
| 2 | Bob Chen | bob@... | $1,890.50 |
...

Example 3: Creating Tables and Migrations

You: I need a reviews table. Each review should belong to a user
and a product, have a rating (1-5), title, body, and timestamps.
Add appropriate RLS policies so users can only edit their own reviews
but everyone can read all reviews.

AI: I'll create the table and RLS policies for you.
[Calls apply_migration with the SQL]

Done. I created:
- The reviews table with all specified columns
- A foreign key to users(id) and products(id)
- A CHECK constraint for rating between 1 and 5
- RLS policy: anyone can SELECT
- RLS policy: authenticated users can INSERT (with user_id = auth.uid())
- RLS policy: users can UPDATE/DELETE only their own reviews

Example 4: Debugging Issues

You: Users are reporting that the checkout is failing.
Check if there are any recent failed orders and what errors
are being logged.

AI: Let me investigate.
[Calls execute_sql - queries orders with error status]
[Calls execute_sql - checks edge function logs]

I found the issue. There are 23 failed orders in the last hour,
all with the error "stripe_payment_intent_failed." The edge function
logs show a 401 Unauthorized response from Stripe. It looks like
the Stripe API key may have expired or been rotated.

Method 2: Community Postgres MCP Server

If you want broader PostgreSQL access beyond the Supabase-specific tools, you can use the Postgres MCP server with your Supabase connection string:

{
  "mcpServers": {
    "supabase-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:your-password@db.your-project-id.supabase.co:5432/postgres"
      ]
    }
  }
}

Find your connection string in the Supabase Dashboard under Settings > Database > Connection String.

Security Best Practices

Practice	Why It Matters
Use the service role key only for MCP	The anon key has limited permissions
Never commit keys to version control	Add config files to .gitignore
Use a dedicated Supabase project for dev/testing	Avoid running AI queries on production data
Review SQL before execution	Some MCP clients show the SQL before running it
Enable RLS on all tables	Even with service role access, RLS is good practice
Use read-only credentials when possible	Create a read-only Postgres role for exploration

Creating a read-only role for safer MCP access:

-- Run this in your Supabase SQL Editor
CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'your-secure-password';
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

Then use this role's connection string in your MCP configuration for read-only access.

Troubleshooting

Issue	Solution
MCP server not showing in Claude Desktop	Check JSON syntax in config file, restart Claude
"Connection refused" error	Verify your Supabase URL and that the project is active
"Permission denied" errors	Ensure you are using the service_role key, not anon
Slow queries	MCP queries are limited to 30 seconds; optimize your SQL
Tools not appearing	Run npx @supabase/mcp-server-supabase@latest --help to verify installation

Conclusion

The Supabase MCP server transforms how you interact with your database. Instead of switching between your editor, the Supabase dashboard, and a SQL client, you can explore data, create tables, write migrations, and debug issues all through natural conversation with your AI assistant. The setup takes less than five minutes, and the productivity gains are immediate.

If your Supabase-powered application needs AI-generated media -- such as user avatars, promotional videos, or voice content -- Hypereal AI provides pay-as-you-go APIs for AI image generation, video creation, talking avatars, and voice cloning that integrate cleanly into any Supabase backend.