Supabase MCP Server: Complete Setup Guide for Claude and Cursor (2026)
How to connect your Supabase database to Claude Desktop, Cursor, and Windsurf using the official Supabase MCP server. Query tables, run migrations, and manage your project with AI.
TLDR: Supabase has an official MCP server that connects your Supabase project to Claude, Cursor, and other MCP-compatible AI tools. You authenticate with a Supabase Personal Access Token, and the server exposes your tables, schemas, and SQL execution as tools the AI can use directly.
Last modified: March 22, 2026 | Published: March 22, 2026
---
Why Connect Supabase to Your AI IDE
Supabase is the most popular open-source Firebase alternative — PostgreSQL-based with a generous free tier and tight integration with Next.js, React, and modern web stacks. Connecting it to your AI assistant via MCP means:
This guide covers setup for Claude Desktop, Cursor, and Windsurf.
---
Prerequisites
---
Step 1: Get Your Supabase Personal Access Token
The Supabase MCP server authenticates using a Personal Access Token (not your project's anon key).
1. Go to supabase.com/dashboard/account/tokens
2. Click Generate new token
3. Name it something like "MCP Server"
4. Copy the token immediately — it won't be shown again
Keep this token secure. It has access to all your Supabase projects, not just one.
---
Step 2: Get Your Project Reference ID
Each Supabase project has a unique reference ID. Find it at:
supabase.com/dashboard/project/[your-project-ref]/settings/general
It looks like: abcdefghijklmnop (a 20-character alphanumeric string)
You'll also find it in your project URL: https://[project-ref].supabase.co
---
Step 3: Configure Claude Desktop
Open your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Supabase MCP server:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref", "your-project-ref-here"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "your-personal-access-token-here"
}
}
}
}
Replace your-project-ref-here and your-personal-access-token-here with your actual values.
Restart Claude Desktop completely. You should see a hammer icon (🔨) in the Claude interface indicating MCP tools are available.
---
Step 4: Configure Cursor IDE
In Cursor, MCP can be configured globally or per-project.
Global config (~/.cursor/mcp.json):
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref", "your-project-ref"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "your-token"
}
}
}
}
Project config (.cursor/mcp.json in your project root — good for team setups):
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref", "your-project-ref"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
}
}
}
}
Using ${SUPABASE_ACCESS_TOKEN} with a project config means each developer stores their own token in their shell environment, avoiding accidental token commits to version control.
---
Step 5: Configure Windsurf IDE
For Windsurf, edit ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref", "your-project-ref"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "your-token"
}
}
}
}
Restart Windsurf after saving.
---
What Tools the Supabase MCP Server Exposes
Once connected, your AI assistant gains access to these tools:
| Tool | What It Does |
|------|-------------|
| list_tables | Lists all tables in your public schema |
| get_table_schema | Returns column definitions, types, and constraints for a table |
| execute_sql | Runs a SQL query and returns results |
| list_extensions | Shows installed PostgreSQL extensions |
| get_project_url | Returns your project's API URL |
| list_storage_buckets | Lists storage buckets |
| list_edge_functions | Shows deployed edge functions |
| get_logs | Fetches recent project logs |
The most powerful combination is get_table_schema + execute_sql — this lets the AI understand your data structure and run queries in context.
---
Practical Examples: What You Can Do
Understand Your Schema
> "List all my tables and describe what each one is for based on the column names"
The AI will call list_tables, then get_table_schema for each, and give you a human-readable summary of your database architecture.
Write Type-Safe TypeScript Interfaces
> "Generate TypeScript interfaces for all my database tables"
With full schema access, the AI generates perfectly typed interfaces:
// Generated from your actual Supabase schema
export interface User {
id: string; // uuid
email: string;
full_name: string | null;
created_at: string; // timestamptz
subscription_tier: 'free' | 'pro' | 'enterprise';
}export interface Post {
id: number; // bigint
user_id: string; // references users.id
title: string;
content: string | null;
published: boolean;
published_at: string | null;
}
Analyze Your Data
> "How many users signed up each day this week?"
The AI will write and execute:
SELECT
DATE(created_at) as day,
COUNT(*) as signups
FROM users
WHERE created_at >= NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at)
ORDER BY day DESC;
...and return the results directly in the chat.
Write Migrations
> "Add a stripe_customer_id column to the users table. Make it nullable, add an index."
The AI generates:
ALTER TABLE users
ADD COLUMN stripe_customer_id TEXT;CREATE INDEX idx_users_stripe_customer_id
ON users(stripe_customer_id)
WHERE stripe_customer_id IS NOT NULL;
With schema context, it knows the table already exists and generates the correct ALTER TABLE syntax instead of a CREATE TABLE statement.
Debug RLS Policies
> "Check if my Row Level Security policies are set up correctly for the posts table"
The AI queries your schema, reviews your existing policies, and identifies gaps or misconfigurations — something that normally requires significant context-switching between your IDE and the Supabase dashboard.
---
Security Considerations
Personal Access Token Scope
Your PAT has access to all Supabase projects in your account. This is broader than necessary if you only want MCP access to one project. Future versions of the Supabase MCP server may support project-scoped tokens.
For now, best practices:
What the AI Can Execute
With execute_sql available, the AI assistant can in principle run any SQL statement your Supabase role is authorized to execute. By default, Supabase MCP uses your project's service role, which has full database access.
Consider setting --read-only mode if you only want the AI to read data and not modify it:
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--project-ref", "your-ref",
"--read-only"
]
Data Sensitivity
Any data the AI reads (query results, schema info) becomes part of the context sent to the AI model for processing. Avoid running MCP queries against tables with highly sensitive PII if you have concerns about data handling.
---
Connecting Multiple Supabase Projects
If you work with multiple Supabase projects (common in agencies or multi-product companies), you can connect all of them:
{
"mcpServers": {
"supabase-prod": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref", "prod-ref"],
"env": { "SUPABASE_ACCESS_TOKEN": "your-token" }
},
"supabase-staging": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref", "staging-ref"],
"env": { "SUPABASE_ACCESS_TOKEN": "your-token" }
}
}
}
The AI will distinguish between them by name. You can ask: "Compare the schema in supabase-prod vs supabase-staging — are there any differences?"
---
Troubleshooting
"Could not find package" Error
npm install -g @supabase/mcp-server-supabase
Try installing globally first, then use node instead of npx:
"command": "node",
"args": ["/usr/local/lib/node_modules/@supabase/mcp-server-supabase/dist/index.js", "--project-ref", "your-ref"]
Authentication Errors
Verify your PAT is correct and hasn't expired. Test it directly:
curl -H "Authorization: Bearer your-token" \
https://api.supabase.com/v1/projects
This should return a list of your projects as JSON.
"Project not found" Error
Double-check your project reference ID. It should be the alphanumeric string in your Supabase dashboard URL, not your project name.
Server Starts but No Tools Available
Restart your IDE completely. MCP servers initialize at startup; a reload is usually not sufficient.
---
Frequently Asked Questions
Does the Supabase MCP server work with local Supabase instances?
Yes — use --local flag instead of --project-ref to connect to a locally running Supabase instance (supabase start).
Can I use this with Claude.ai (web version)?
No — the web version of Claude doesn't support MCP. You need Claude Desktop, Cursor, or Windsurf.
Does it work with the Supabase free tier?
Yes, there are no plan restrictions on using the MCP server.
Is there a Python version of the Supabase MCP server?
The official Supabase MCP server is Node.js-based. Community Python implementations exist but are not officially maintained.
Can the AI create new tables through MCP?
Yes — execute_sql allows DDL statements (CREATE TABLE, ALTER TABLE, etc.) unless you're using --read-only mode.