Writing SQL to answer a quick business question is one of those tasks that takes ten seconds if you already know the schema and ten minutes if you don't. The Supabase MCP server eliminates the friction entirely: connect Claude to your Supabase project once, and from that point on you can just ask — "how many users signed up this week?" or "which products are low on stock?" — and get an immediate answer without opening a database client.

What is Supabase?

Supabase is an open-source backend platform built on top of Postgres. It gives you a fully managed relational database, auto-generated REST and GraphQL APIs, authentication, storage, and edge functions — all deployable in minutes via the web dashboard. Because it is built on standard Postgres, every SQL skill you already have transfers directly. Supabase is popular with indie developers and startups who want Firebase-level convenience without giving up SQL power. The free tier includes a real Postgres database with no time limit, making it accessible for personal projects.

What the Supabase MCP Server Does

The Supabase MCP server acts as a secure bridge between Claude and your Supabase Postgres database. Once configured, Claude gains access to a set of database tools it can call during your conversation:

  • List tables — see every table in your public schema at a glance
  • Inspect table schema — get column names, types, and constraints for any table
  • Run SELECT queries — query data using natural language that Claude converts to SQL
  • Check row counts — quickly find out how many records are in any table
  • List database functions — discover stored procedures and functions in your project
  • Read storage buckets — inspect what files are stored in Supabase Storage

Claude handles the SQL translation. You describe what you want in plain English, Claude writes the appropriate query behind the scenes, executes it via the MCP server, and returns the result in a readable format.

Prerequisites

Before installing the Supabase MCP server, make sure you have the following:

  • Supabase project — the free tier works perfectly. Create one at supabase.com if you don't have one.
  • Service role key — go to your Supabase dashboard, then Project Settings → API. Copy the service_role key (not the anon key). Treat this like a root password — it bypasses Row Level Security.
  • Project URL — on the same API settings page, copy your Project URL (format: https://your-project-ref.supabase.co).
  • Node.js 18+ — check with node --version. Download from nodejs.org if needed.
  • Claude Desktop — installed and signed in.

How to Install the Supabase MCP Server

  1. Locate your Claude Desktop config file. On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.
  2. Open the config file in any text editor (VS Code, Notepad++, or even Notepad).
  3. Add the Supabase server entry inside the mcpServers object. See the full config JSON below.
  4. Replace the placeholder values — swap in your actual project URL and service role key.
  5. Save the file and fully quit Claude Desktop (not just close the window — use Quit from the system tray or menu bar).
  6. Relaunch Claude Desktop. You should see a hammer icon in the chat input area, indicating MCP tools are active.
  7. Test the connection by typing: "List all the tables in my Supabase database." Claude should respond with your table list.

Configuration JSON

Add this block to your claude_desktop_config.json. If you already have other MCP servers configured, add the supabase entry inside the existing mcpServers object.

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase", "--project-url", "https://your-project.supabase.co"],
      "env": {
        "SUPABASE_SERVICE_ROLE_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}
Replace https://your-project.supabase.co with your actual project URL and the placeholder key with your real service role key.

Real Use Cases

Here are five concrete prompts you can use once the server is connected:

  1. "Show me all users who signed up in the last 7 days" — Claude queries your auth.users table (or equivalent) with a date filter and returns a formatted list. Useful for weekly growth tracking without opening Supabase Studio.
  2. "How many active subscriptions do we have right now?" — Claude counts rows in your subscriptions table filtered by status. Great for quick business metrics during a meeting.
  3. "List the columns in the orders table" — Claude inspects the schema and returns each column name, data type, and whether it's nullable. A lifesaver when you're deep in development and can't remember if that field was varchar or text.
  4. "Find all rows in products where stock_count is less than 10" — Claude translates this to a WHERE clause and returns your low-stock items. Faster than building a filter in any UI.
  5. "Run this SQL and tell me what it returns: SELECT COUNT(*) FROM sessions WHERE created_at > NOW() - INTERVAL '1 hour'" — Claude executes the raw SQL directly and explains the output. Handy when you need to run a specific query without opening a database client.

Pros

  • Natural language SQL is genuinely powerful for analytics. Non-technical teammates can query the database without writing a single line of SQL — just describe what they need.
  • Schema inspection saves time during development. Instead of switching to Supabase Studio to check a table structure, ask Claude mid-conversation.
  • Free tier is enough for personal projects. You don't need a paid Supabase plan to use this MCP server, making it accessible for indie developers and side projects.
  • No extra infrastructure required. The MCP server runs locally via npx — there's nothing to deploy or host.

Cons and Limitations

  • Service role key bypasses Row Level Security. This is the biggest risk. If you accidentally expose this key or use it carelessly, Claude could read or modify any data in your database, regardless of your RLS policies. Use a read-only Postgres role for production analytics.
  • Write operations require careful scoping. The MCP server may support INSERT or UPDATE operations depending on the version. If you only need read access, explicitly restrict Claude to SELECT queries or use a read-only database credential.
  • Not suitable for large result sets. Queries that return thousands of rows may be slow or truncated in Claude's context window. Design your queries to return summary data rather than raw dumps.

Frequently Asked Questions

The service role key bypasses Row Level Security (RLS) entirely, so it should be treated like a root password. Never share it, never commit it to version control, and consider using a scoped read-only Postgres role for analytics use cases instead. Store it only in your claude_desktop_config.json env block, which is a local file on your machine.

Yes — because the service role key has full database access, Claude can technically run INSERT, UPDATE, and DELETE queries if the MCP server exposes those tools. Always review what operations the specific MCP server package supports, and consider restricting Claude to a read-only Postgres role if you only need analytics queries.

Yes. Supabase's free tier gives you a full Postgres database with a service role key, and the MCP server works with it. The free tier has connection and storage limits, but for personal projects and development use it is more than sufficient.

Yes, and this is strongly recommended for production use. Create a Postgres role with SELECT-only permissions on the tables Claude needs to access, then provide those credentials instead of the service role key. This limits blast radius if the credentials are ever exposed.