Supabase MCP: How to Connect AI to Your Database

You're deep in a coding session and need to inspect your database schema. You switch to the browser, log into the Supabase dashboard, find the right project, open the SQL editor, run a query, then jump back to your code. Five minutes later, you need another query. Same dance again. And that's before the real friction starts: writing the right SQL, interpreting the results, iterating, etc.

This context-switching kills momentum. Supabase MCP eliminates it entirely by letting AI tools like Claude and Cursor talk directly to your database.

Key Takeaways

• Supabase MCP connects AI assistants (Claude, Cursor, Windsurf) directly to your Supabase projects
• No personal access token required anymore—authentication happens through browser-based OAuth
• Remote MCP is the recommended approach, connecting to https://mcp.supabase.com/mcp
• Never connect to production—Supabase MCP is designed for development environments only
• Read-only mode is available when you need to query real data safely
• Works alongside Desktop Commander for complete local + cloud development

The Frustrating Reality of Database Work

Every developer and most data analysts who work with databases knows this workflow: write code, wonder about the schema, open dashboard, find project, check tables, go back to code, realize you need another query, repeat.

One developer shared on Reddit:

"I struggled for hours last night because I skipped this step at first. Without this, Cursor just couldn't get accurate context from Supabase, even when I fed it the docs directly."

Another user in a GitHub discussion described giving up entirely:

"We were not able to make it work. We gave up on working on it."

The setup doesn't have to be this painful. Once you understand how Supabase MCP works, the configuration takes minutes—and transforms how you interact with your database.

What Supabase MCP Actually Does

If you're new to MCP (Model Context Protocol), it's an open standard that lets AI tools communicate with external systems. Supabase built an official MCP server that exposes your projects to AI assistants.

Here's what becomes possible:

Capability	What You Can Do	Example Prompt
Schema Management	List tables, create migrations, modify structure	"Show me all tables in my project and their relationships"
SQL Queries	Run SELECT, INSERT, UPDATE directly	"Find all users who signed up in the last 7 days"
Project Management	Create, pause, restore projects	"Create a new Supabase project called staging-api"
Edge Functions	List, view, deploy serverless functions	"Deploy this edge function to handle webhooks"
Debugging	Access logs, get performance advisors	"Show me the last 100 auth service logs"
TypeScript Types	Generate types from your schema	"Generate TypeScript types for my database"

The full list of available tools includes over 30 operations organized into feature groups you can enable or disable.

Two Connection Methods Compared

Supabase offers two ways to connect MCP to your projects:

Method	Best For	Authentication	Features
Remote MCP	Most users, Claude/Cursor	Browser OAuth (automatic)	Full feature set
Local CLI	Local development, testing	None required	Limited tools

Remote MCP is the recommended approach. It connects to Supabase's hosted MCP server at https://mcp.supabase.com/mcp and handles authentication automatically through your browser.

Local CLI runs at http://localhost:54321/mcp when you have Supabase running locally. Useful for testing, but doesn't include OAuth or the full tool set.

For most development workflows, remote MCP gives you everything you need.

Setting Up Supabase MCP with Cursor

Cursor has the smoothest setup experience. Add this to your .cursor/mcp.json file:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Restart Cursor, and it will prompt you to authenticate with Supabase through your browser. Select the organization you want to grant access to, and you're connected.

To scope the connection to a specific project (recommended):

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=your-project-id"
    }
  }
}

Find your project reference in your Supabase dashboard URL—it's the string after project/.

Setting Up Supabase MCP with Claude Desktop

For Claude Desktop, the configuration goes in claude_desktop_config.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"]
    }
  }
}

Alternatively, you can use the remote server URL directly if your Claude Desktop version supports HTTP MCP servers.

If you're already using Desktop Commander with Claude, you can run both MCP servers together—Desktop Commander for local file and terminal access, Supabase MCP for database operations.

Setting Up Supabase MCP with Desktop Commander

If you already use Desktop Commander, you don't need to touch configuration files at all.

You can simply ask Desktop Commander to set up Supabase MCP for you. Just provide the required configuration details, and it will handle the rest—updating the necessary files and restarting your Claude Desktop client automatically.

Under the hood, this results in the same configuration as below being added to claude_desktop_config.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"]
    }
  }
}

SQL Through Natural Language

Once connected, database exploration becomes conversational. You no longer need to write SQL, remember syntax, or even know how your database is structured.

You can simply ask your AI, in natural language, to explore, analyze, and reason about your data—and it will write and execute the necessary queries for you.

This changes who can work with databases. What used to require SQL knowledge and data expertise becomes accessible to anyone: product managers, operators, founders, analysts, and non-technical teammates. Here are a few example prompts that demonstrate this workflow:

Exploring schema:

List all tables in my database and describe their columns. Highlight any tables that seem related through foreign keys.

Writing queries:

Write a query to find the top 10 customers by total order value in the last 30 days.

Creating migrations:

Add a 'status' column to the orders table with values 'pending', 'processing', 'shipped', 'delivered'. Default to 'pending'.

Debugging issues:

Show me the last 50 error logs from the auth service. Are there any patterns?

Generating types:

Generate TypeScript types for my entire database schema. I'm using Supabase's type generation format.

The MCP server translates these requests into actual SQL operations and returns real results from your database.

Security: The Non-Negotiables

Supabase is explicit about this: never connect MCP to production data. The official documentation emphasizes this repeatedly, and for good reason.

The primary risk is prompt injection. If malicious instructions get embedded in your database content, they could trick the AI into executing unauthorized commands. In a development environment with test data, this is manageable. In production with real customer data, it's a serious vulnerability.

Security best practices:

1. Use development projects only with synthetic or obfuscated data
2. Enable read-only mode if you must query real data: ?read_only=true
3. Scope to specific projects rather than granting organization-wide access
4. Disable unused feature groups to minimize attack surface
5. Keep manual approval enabled in your MCP client—review each operation before execution
6. Use database branching to test schema changes safely

To configure read-only mode:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?read_only=true&project_ref=your-project-id"
    }
  }
}

Read-only mode disables migrations, project creation/deletion, edge function deployment, and storage configuration changes.

Feature Groups: Enable Only What You Need

Supabase MCP organizes tools into feature groups. By default, most are enabled, but you can restrict access:

Feature Group	Includes	Risk Level
account	Project management, organization access	Medium
database	Schema, queries, migrations	High
debugging	Logs, performance advisors	Low
development	URLs, keys, type generation	Low
docs	Documentation search	None
functions	Edge Functions deployment	Medium
storage	Bucket management (disabled by default)	Medium
branching	Database branching (experimental)	Medium

To enable only specific groups:

https://mcp.supabase.com/mcp?features=database,debugging,docs

This gives you schema access and debugging without the ability to deploy functions or manage projects.

Combining Supabase MCP with Desktop Commander

A powerful setup combines Supabase MCP for cloud database access with Desktop Commander for local development. This mirrors how the best MCP servers complement each other.

With both configured:

• Use Desktop Commander to navigate your codebase, run Docker containers, and execute terminal commands
• Use Supabase MCP to query your database, generate migrations, and deploy edge functions
• Let Claude review your code while simultaneously checking how it interacts with your database schema

The Desktop Commander prompt library includes templates for full-stack workflows that combine local and cloud operations.

Troubleshooting Common Issues

Authentication not working: Clear your browser cache and try the OAuth flow again. Some browsers block the redirect silently.

"Project not found" errors: Double-check your project_ref parameter. The project reference is the alphanumeric ID in your dashboard URL, not the project name.

Tools not appearing: Restart your MCP client after configuration changes. MCP tools are loaded at startup.

Read-only blocking operations: If you enabled read_only=true, migrations and certain operations are intentionally disabled. Remove the parameter if you need write access.

Rate limiting: Supabase MCP has usage limits. If you're hitting them, reduce the frequency of queries or batch operations together.

Frequently Asked Questions

Can I use Supabase MCP with production databases? ▾

Technically yes, but Supabase strongly advises against it. Use development projects with test data. If you must access real data, enable read-only mode and review every operation manually.

Does Supabase MCP work with self-hosted Supabase? ▾

The remote MCP server connects to Supabase Cloud. For self-hosted instances, you can enable the local MCP server, though it has reduced functionality.

What's the difference between Supabase MCP and just using the SQL editor? ▾

Context. With MCP, your AI assistant can see your codebase and your database simultaneously, suggesting queries that match your application's data model and catching mismatches between code and schema.

Can I use multiple MCP servers at once? ▾

Yes. Many developers run Desktop Commander alongside Supabase MCP and other specialized servers. Each handles different capabilities.

Is there a cost to using Supabase MCP? ▾

The MCP server itself is free. Standard Supabase pricing applies to your projects and any resources consumed.

Connecting AI to your database removes one of the biggest friction points in modern development. With Supabase MCP configured, schema exploration, query writing, and debugging happen in the same context as your code—no more dashboard dancing.