Supabase MCP: Connect AI Agents to Your Database

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Instead of copy-pasting schema into a chat window, you give the AI a live connection. It can read, query, and act on real data.

Supabase publishes an official MCP server. Connect it to Claude, Cursor, or another MCP-compatible client, and the AI gets direct access to your Supabase project.

What the Supabase MCP server does

The Supabase MCP server exposes your project through a set of tools that an AI agent can call. Once connected, the agent can:

• List all tables in your database
• Inspect schema, columns, and types
• Query data with SQL
• Execute migrations
• Manage Supabase Edge Functions
• Interact with Supabase Storage
• Read and write project configuration

This means you can ask Claude "what tables exist in my project?" and get an actual answer, not a guess based on training data.

Setting it up with Claude Desktop

First, get a Supabase access token. Go to your Supabase dashboard, open Account settings, then Access tokens, and generate a new token. Copy it.

Open your Claude Desktop config file. On macOS it's at ~/Library/Application Support/Claude/claude_desktop_config.json. Add the Supabase MCP server to the mcpServers object:

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

Replace YOUR_SUPABASE_ACCESS_TOKEN with the token you copied. Save the file and restart Claude Desktop.

You should see a hammer icon in the chat interface indicating MCP tools are available. You can ask Claude to list your projects or describe a table to confirm it's working.

Setting it up with Cursor

Create or edit .cursor/mcp.json in your project root (or the global Cursor MCP config at ~/.cursor/mcp.json):

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

After saving, open Cursor's settings and confirm the MCP server shows as connected under Tools. Cursor's Composer mode will now have access to your Supabase project when you work on database-related code.

Setting it up with Claude Code

If you use Claude Code (the CLI), add the MCP server to your project's .claude/mcp.json:

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

You can also add it globally using claude mcp add from the command line. Once configured, Claude Code can inspect your schema and generate accurate migration files without you having to paste DDL into every conversation.

What you can actually do once connected

With the MCP server running, the AI has access to tools it can call autonomously during a conversation. Some concrete examples:

Schema exploration. Ask "what columns does the orders table have?" and the AI calls the schema tool and gives you a real answer. No more guessing based on your description.

SQL generation and execution. Ask Claude to write a query and run it. It can iterate on the SQL, see the results, and adjust. This works for reporting queries, data audits, and one-off lookups.

Migration authoring. Describe the change you want ("add a status column to invoices, default to pending") and Claude can write the migration SQL, check it against your existing schema, and apply it via the Supabase CLI integration.

Debugging. If a query is returning wrong results, you can ask the AI to inspect the relevant tables and RLS policies directly rather than walking through them yourself.

Security considerations

The MCP server authenticates with your personal access token, which means it has the same permissions you do on that project. That includes read and write access to your data, schema changes, and project configuration.

A few things worth doing before you connect a production project:

Use a dedicated development project. If you're experimenting or building features, point the MCP server at a dev or staging project, not production. Mistakes made by an AI agent are the same as mistakes made by you.

Create a read-only database role. If you need to connect to production for read operations, create a restricted PostgreSQL role and use that connection. The MCP server's Supabase API token will still have broad access, but you can limit what SQL the agent can run.

Treat the token like a password. Don't commit it to your repo. Use environment variable substitution if your MCP client supports it.

Limitations

MCP runs locally. The AI agent calls tools on your machine, which then make API calls to Supabase. The AI doesn't have a direct cloud-to-cloud connection to your database.

This means:

• You need to have the MCP server running (your machine must be on)
• The agent can't be triggered by external events without you initiating the conversation
• It won't work in automated pipelines or CI without additional setup

The Supabase MCP server also works through the Supabase Management API, not a direct database connection. Some low-level PostgreSQL operations aren't available through the API layer.

Alternatives

Supabase's built-in AI assistant. The Supabase dashboard has an AI assistant that understands your project's schema. It's useful for quick SQL generation and explaining tables. It doesn't require any setup, but it's scoped to the dashboard and doesn't integrate with your editor or CLI workflow.

pg_mcp. If you want direct PostgreSQL access rather than the Supabase API layer, pg_mcp is an MCP server that connects to any PostgreSQL database over a standard connection string. You lose Supabase-specific features (storage, auth, edge functions), but gain lower-level database access and compatibility with any Postgres host.

Direct database connection via MCP. Some MCP clients support running arbitrary SQL via a connection string. This bypasses the Supabase API entirely and works at the Postgres level, which is useful for complex schema work or databases not hosted on Supabase.

The Supabase MCP server is a practical addition to any workflow that involves regular schema changes, data exploration, or writing database-heavy code. The setup takes about five minutes, and having an AI that can inspect your actual tables rather than approximate them from description makes a noticeable difference.