Supabase MCP Server: Database Context for Claude Code

Supabase and Claude Code are a powerful combination. With the Supabase MCP server, Claude can design your database schema, write migrations, query data, and even create new projects—all from natural language commands.

This guide walks you through setting up Supabase MCP and using it effectively for database-powered development.

How to connect Supabase to Claude Code, design schemas with AI assistance, generate type-safe queries, and follow best practices for secure database development.

What is Supabase MCP?

Supabase MCP is an official integration that connects your Supabase projects to Claude Code (and other AI tools). Once connected, Claude can:

Design and manage schemas — Create tables, define relationships, add indexes
Write migrations — Generate SQL migration files with proper versioning
Query data — Execute SQL and analyze results
Manage projects — Create branches, configure settings, handle TypeScript types
Debug issues — Access logs and troubleshoot problems

Think of it as giving Claude direct database access—but with guardrails.

---

Prerequisites

Before starting:

Supabase account with at least one project
Claude Code installed and configured
A development project (not production—we'll explain why)

---

Part 1: Setting Up Supabase MCP

Supabase now supports remote MCP, which means no tokens or local configuration required.

Go to supabase.com/dashboard and select your project.

In the sidebar, go to Project Settings → MCP Connection (or look for the MCP tab in your project settings).

Click to generate a custom MCP URL for your project. Copy this URL.

Run the following command, replacing the URL with your generated one:

``bash


    claude mcp add supabase --url "your-mcp-url-here"


  
  
    Check that the server is connected:

`bash


    claude mcp list

You should see supabase listed with its available tools.


Alternative: Using the Community Package
You can also use the community MCP package:

bash
claude mcp add-json "supabase" '{
  "command": "npx",
  "args": ["-y", "@supabase/mcp-server"],
  "env": {
    "SUPABASE_URL": "https://your-project.supabase.co",
    "SUPABASE_SERVICE_KEY": "your-service-key"
  }
}'



  The service key has full database access. Never commit it to version control. Use the remote MCP method when possible—it's more secure.

---
Part 2: Designing Database Schemas
With Supabase MCP connected, Claude becomes a powerful database architect.
Creating Tables


Create a users table with:
id (uuid, primary key)
email (text, unique)
full_name (text)
avatar_url (text, nullable)
created_at (timestamp with timezone)
updated_at (timestamp with timezone)


Claude will generate the SQL and execute it against your database.
Defining Relationships


I need a posts table that belongs to users. Each post should have:
title
content (markdown)
published boolean
publish date

Also create a comments table where users can comment on posts.


Claude understands relational design patterns and will create appropriate foreign keys.
Adding Indexes


Add indexes to optimize:
Looking up users by email
Querying posts by user and published status
Finding comments by post


---
Part 3: Working with Migrations
Supabase uses migrations for schema versioning. Claude can generate these properly.
Generate a Migration


Generate a migration to add a 'role' column to the users table
with values 'admin', 'editor', or 'viewer'. Default to 'viewer'.


Claude creates a timestamped migration file:

sql
-- 20250115120000_add_user_roles.sql
ALTER TABLE users
ADD COLUMN role TEXT NOT NULL DEFAULT 'viewer'
CHECK (role IN ('admin', 'editor', 'viewer'));


Review Before Applying


Show me all pending migrations before I apply them


Rollback Strategy


Create a rollback migration for the roles change


---
Part 4: Querying Data
Claude can write and execute SQL queries directly.
Basic Queries


Show me the 10 most recent posts with their author names


How many users signed up in the last 30 days?


Complex Analytics


Create a report showing:
Total posts per user
Average time between posts
Most active posting days


Type-Safe Queries


Generate TypeScript types for the users and posts tables


Claude generates Supabase-compatible TypeScript:

typescript
export interface Database {
  public: {
    Tables: {
      users: {
        Row: {
          id: string
          email: string
          full_name: string
          avatar_url: string | null
          created_at: string
          updated_at: string
          role: 'admin' | 'editor' | 'viewer'
        }
        Insert: {
          id?: string
          email: string
          full_name: string
          avatar_url?: string | null
          created_at?: string
          updated_at?: string
          role?: 'admin' | 'editor' | 'viewer'
        }
        Update: {
          id?: string
          email?: string
          full_name?: string
          avatar_url?: string | null
          created_at?: string
          updated_at?: string
          role?: 'admin' | 'editor' | 'viewer'
        }
      }
      // ... more tables
    }
  }
}


---
Part 5: Row Level Security (RLS)
Supabase's RLS is critical for security. Claude can help design policies.
Enable RLS


Enable RLS on the posts table. Users should only see:
Their own posts (published or not)
Other users' published posts


Claude generates:

sql
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-- Users can view their own posts
CREATE POLICY "Users can view own posts" ON posts
  FOR SELECT
  USING (auth.uid() = user_id);
-- Anyone can view published posts
CREATE POLICY "Anyone can view published posts" ON posts
  FOR SELECT
  USING (published = true);
-- Users can only insert/update/delete their own posts
CREATE POLICY "Users can manage own posts" ON posts
  FOR ALL
  USING (auth.uid() = user_id);


Test RLS Policies


Test the posts RLS policies - try to access another user's draft


---
Part 6: Using Claude Code Templates
Supabase provides pre-built Claude Code agents and commands for common tasks.
Install the Schema Architect Agent

bash
npx claude-code-templates@latest --agent database/supabase-schema-architect


This installs a specialized agent that:
Understands Supabase best practices
Generates optimized schemas
Handles migrations properly
Sets up RLS by default

Install Database Commands

bash
npx claude-code-templates@latest --mcp database/supabase


Adds shortcuts for common operations:

/supabase schema — Show current schema

/supabase types — Generate TypeScript types

/supabase logs — View recent logs

/supabase branch — Manage database branches


---
Part 7: Best Practices

  
    title="Use Development Projects"
    description="Never connect production databases. LLMs can make mistakes. Use development or staging for AI-assisted work."
  />
  
    title="Review Before Executing"
    description="Ask Claude to show SQL before running it. Verify migrations before applying them."
  />
  
    title="Enable RLS First"
    description="Enable Row Level Security before adding data. It's harder to retrofit security."
  />
  
    title="Use Migrations"
    description="Always use migrations for schema changes. They provide history and rollback capability."
  />

Safe Prompting Patterns
Do:


Design a schema for... (Claude generates, you review)
Show me the SQL before executing
Create a migration for... (not direct ALTER TABLE)


Avoid:


Delete all data from users (dangerous without confirmation)
Drop the posts table (use migrations instead)
Update production database (connect development only)


Data Safety

  The Supabase MCP server has full database access. In development, this is powerful. In production, it's dangerous. Keep your development database populated with test data, not copies of production.

---
Part 8: Debugging with Logs
When things go wrong, Claude can help investigate.
View Recent Logs


Show me the database logs from the last hour


Investigate Errors


I'm getting a foreign key constraint error when inserting posts.
Check the logs and help me understand what's wrong.


Performance Analysis


Which queries are running slowest? Suggest optimizations.


---
Example Workflow
Here's a complete workflow for adding a new feature:

  
    "I need to add a tags system for posts. Posts can have multiple tags,
    and tags can belong to multiple posts."
  
  
    "Generate a migration for the tags system"
  
  
    "Add RLS policies - anyone can read tags, only post owners can modify post tags"
  
  
    "Update TypeScript types for the new tables"
  
  
    "Insert some test data and verify the tag relationships work"
  

---
Available Tools
Once connected, the Supabase MCP server provides these tools:
| Tool | Description |
|------|-------------|

| list_projects | List all your Supabase projects |

| get_schema | Get current database schema |

| execute_sql | Run SQL queries |

| create_migration | Generate migration files |

| apply_migration | Apply pending migrations |

| get_logs | Retrieve database/API logs |

| generate_types | Create TypeScript definitions |

| manage_branches | Handle database branching |


---
Troubleshooting
MCP Not Connecting
Symptom:

claude mcp list

 doesn't show Supabase
Solutions:
Verify your MCP URL is correct
Check internet connectivity
Restart Claude Code
Try the community package method

Permission Errors
Symptom: "Permission denied" when running queries
Solutions:
Verify your service key has correct permissions
Check RLS policies aren't blocking the operation
Ensure you're connected to the right project

Slow Queries
Symptom: Queries taking too long
Solutions:
Ask Claude to analyze the query plan
Add appropriate indexes
Optimize the query structure

---
Combining with CAS
For the best development experience, combine Supabase MCP with CAS:


CAS remembers your schema decisions
cas_remember: Using Supabase with users, posts, and comments tables
CAS tracks database-related tasks
cas_task_create: Implement tag system for posts
CAS stores learned patterns
cas_remember: Always use RLS policies when creating tables

This gives you persistent context about your database architecture across sessions.

---

Conclusion

Supabase MCP transforms database development with Claude Code. Instead of context-switching between your terminal, documentation, and Supabase dashboard, you work conversationally—designing schemas, writing migrations, and debugging issues all through natural language.

Start with a development project, take time to learn the available tools, and always review SQL before execution. With these practices in place, you'll find database development faster and more enjoyable than ever.

Connect your first Supabase project today. Start with schema design—it's the safest way to explore what's possible before moving to data operations.

---

Supabase MCP Server: Database Context for Claude Code

What is Supabase MCP?

Prerequisites

Part 1: Setting Up Supabase MCP

Alternative: Using the Community Package

Part 2: Designing Database Schemas

Creating Tables

Defining Relationships

Adding Indexes

Part 3: Working with Migrations

Generate a Migration

Review Before Applying

Rollback Strategy

Part 4: Querying Data

Basic Queries

Complex Analytics

Type-Safe Queries

Part 5: Row Level Security (RLS)

Enable RLS

Test RLS Policies

Part 6: Using Claude Code Templates

Install the Schema Architect Agent

Install Database Commands

Part 7: Best Practices

Safe Prompting Patterns

Data Safety

Part 8: Debugging with Logs

View Recent Logs

Investigate Errors

Performance Analysis

Example Workflow

Available Tools

Troubleshooting

MCP Not Connecting

Permission Errors

Slow Queries

Combining with CAS

CAS remembers your schema decisions

CAS tracks database-related tasks

CAS stores learned patterns

Conclusion

Resources