Skip to content

Supabase MCP ​

Supabase MCP 是 Supabase 官方提供的 MCP Server,讓 Claude Code 能夠直接管理 Supabase 專案、操作資料庫、部署 Edge Functions。

為什麼需要 Supabase MCP? ​

傳統方式使用 MCP
切換到 Dashboard 查看 SchemaClaude 直接讀取資料庫結構
手動撰寫 SQL MigrationClaude 產生並執行 Migration
複製貼上 API URL、KeyClaude 自動取得正確設定
查文件找 RLS 語法Claude 直接產生正確 Policy
沒有 Supabase MCP:
你:建立一個 posts 表格
Claude:[產生 SQL,你需要自己貼到 Dashboard 執行]
       [可能漏掉 RLS、Index 等設定]

有 Supabase MCP:
你:建立一個 posts 表格
Claude:[查詢現有 Schema 避免衝突]
       [產生完整 SQL 含 RLS]
       [直接執行 Migration]
       [產生 TypeScript 型別]

安裝方式 ​

方法 1:Claude Code CLI(推薦) ​

使用 OAuth 認證(最簡單):

bash
claude mcp add --transport http supabase https://mcp.supabase.com/mcp

首次使用時會自動開啟瀏覽器進行 Supabase 登入授權。

使用 Personal Access Token:

bash
claude mcp add supabase -s project -e SUPABASE_ACCESS_TOKEN=your_token -- npx -y @supabase/mcp-server-supabase@latest

Personal Access Token 在 Supabase Dashboard > Account Settings > Access Tokens 取得。

方法 2:手動 JSON 設定 ​

HTTP Transport(雲端版):

json
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

指定專案和唯讀模式(推薦):

json
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=your-project-ref&read_only=true"
    }
  }
}

使用 PAT(CI 環境):

json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "your-token",
        "SUPABASE_PROJECT_REF": "your-project-ref"
      }
    }
  }
}

方法 3:本地開發(Supabase CLI) ​

如果使用本地 Supabase 開發環境:

bash
# 初始化專案
npx supabase init

# 啟動本地 Supabase
npx supabase start

本地 MCP 端點:http://localhost:54321/mcp

設定選項 ​

MCP URL 支援以下 Query Parameters:

參數說明預設值
project_ref限定存取特定專案全部專案
read_only唯讀模式,防止修改false
features啟用的功能群組(逗號分隔)全部啟用

範例:

https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true&features=database,debugging

功能群組(Feature Groups) ​

Supabase MCP 將工具分為多個群組:

群組說明包含工具
Account專案與組織管理建立專案、列出專案、組織設定
Database資料庫操作(核心)Schema 管理、SQL 執行、Migration
Debugging除錯工具查看 Logs、安全性建議
Development開發輔助API URLs、Auth Keys、TypeScript 型別產生
Edge FunctionsServerless 函數部署、管理 Edge Functions
Knowledge Base文件搜尋搜尋 Supabase 官方文件
Branching分支管理(付費)建立開發分支、合併
Storage儲存空間(預設關閉)Bucket 管理、設定

精簡功能

如果只需要資料庫操作,可以只啟用 database 和 debugging:

?features=database,debugging

使用方式 ​

查詢 Schema ​

What tables are in my Supabase database?
Show me the schema of the users table with all columns and types

執行查詢 ​

Query all users who signed up in the last 7 days
Count the number of orders by status

建立表格與 Migration ​

Create a posts table with title, content, author_id (references users), and timestamps

Claude 會:

  1. 檢查現有 Schema 避免衝突
  2. 產生完整的 SQL(含 RLS)
  3. 建立 Migration 檔案
  4. 執行 Migration

產生 TypeScript 型別 ​

Generate TypeScript types for my Supabase schema

查看 Logs ​

Show me the recent error logs from my Supabase project

安全性最佳實踐 ​

重要安全提醒

Supabase MCP 可以直接操作你的資料庫。請遵循以下最佳實踐:

1. 不要連接 Production ​

❌ 不好:直接連接 Production 資料庫
✅ 好:使用開發專案或本地環境

Supabase 提供 Database Branching(付費),可以安全測試變更。

2. 使用唯讀模式 ​

在探索或查詢時,使用 read_only=true:

json
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?read_only=true"
    }
  }
}

3. 限定專案範圍 ​

避免 MCP 存取所有專案:

json
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=your-dev-project"
    }
  }
}

4. 保持工具審核 ​

Claude Code 會在執行操作前詢問確認。建議保持此設定,不要自動同意所有操作。

5. 使用非生產資料 ​

確保開發環境使用:

  • 測試資料
  • 匿名化資料
  • 模擬資料

與 Next.js 整合 ​

安裝客戶端 ​

bash
npm install @supabase/supabase-js @supabase/ssr

建立客戶端 ​

瀏覽器端:

typescript
// lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

伺服器端:

typescript
// lib/supabase/server.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // Server Component 中無法設定 cookie
          }
        },
      },
    }
  )
}

環境變數 ​

bash
# .env.local
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

本地開發: 執行 npx supabase start 後會顯示這些值。

雲端版本: 在 Supabase Dashboard > Settings > API 取得。

查詢範例 ​

typescript
// app/trips/page.tsx (Server Component)
import { createClient } from '@/lib/supabase/server'

export default async function TripsPage() {
  const supabase = await createClient()

  const { data: trips, error } = await supabase
    .from('trips')
    .select('*')
    .order('created_at', { ascending: false })

  if (error) {
    console.error(error)
    return <div>Error loading trips</div>
  }

  return (
    <div>
      {trips.map((trip) => (
        <div key={trip.id}>{trip.title}</div>
      ))}
    </div>
  )
}

範例:建立完整的 Blog Schema ​

讓 Claude 透過 Supabase MCP 建立完整的 Blog 系統:

Create a complete blog schema with:
- posts table (title, slug, content, excerpt, published, author_id)
- categories table
- posts_categories junction table
- comments table with nested replies
- RLS policies for public read and author write
- Indexes for performance

Claude 會產生並執行完整的 Migration,包含:

sql
-- Posts 表格
CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  content TEXT,
  excerpt TEXT,
  published BOOLEAN DEFAULT false,
  author_id UUID REFERENCES auth.users(id) NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Categories 表格
CREATE TABLE categories (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT UNIQUE NOT NULL,
  slug TEXT UNIQUE NOT NULL
);

-- Junction 表格
CREATE TABLE posts_categories (
  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
  category_id UUID REFERENCES categories(id) ON DELETE CASCADE,
  PRIMARY KEY (post_id, category_id)
);

-- Comments 表格(支援巢狀)
CREATE TABLE comments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
  parent_id UUID REFERENCES comments(id) ON DELETE CASCADE,
  author_id UUID REFERENCES auth.users(id),
  content TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- RLS
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
ALTER TABLE comments ENABLE ROW LEVEL SECURITY;

-- 公開讀取已發布文章
CREATE POLICY "Public can read published posts"
  ON posts FOR SELECT
  USING (published = true);

-- 作者可以管理自己的文章
CREATE POLICY "Authors can manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = author_id);

-- 效能 Index
CREATE INDEX posts_slug_idx ON posts(slug);
CREATE INDEX posts_author_idx ON posts(author_id);
CREATE INDEX comments_post_idx ON comments(post_id);

驗證安裝 ​

在 Claude Code 中執行:

/mcp

應該會看到 supabase 顯示為 connected。

測試是否正常運作:

List all tables in my Supabase database

故障排除 ​

OAuth 認證失敗 ​

  1. 確認瀏覽器已登入 Supabase
  2. 檢查是否有組織權限
  3. 嘗試重新授權

無法連接到專案 ​

  1. 確認 project_ref 正確
  2. 檢查 Personal Access Token 權限
  3. 確認專案未被暫停

操作被拒絕 ​

  1. 檢查是否使用 read_only 模式
  2. 確認使用者有足夠權限
  3. 檢查 RLS Policy 設定

搭配其他 MCP ​

  • Supabase MCP + Context7:取得最新 Supabase 文件語法
  • Supabase MCP + Playwright MCP:測試 Supabase 驅動的 UI
  • Supabase MCP + shadcn MCP:建立 Supabase 資料驅動的 UI 元件

參考資源 ​

下一步 ​

AI 時代的軟體工程工作坊教學手冊