Supabase MCP

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

為什麼需要 Supabase MCP？

傳統方式	使用 MCP
切換到 Dashboard 查看 Schema	Claude 直接讀取資料庫結構
手動撰寫 SQL Migration	Claude 產生並執行 Migration
複製貼上 API URL、Key	Claude 自動取得正確設定
查文件找 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 Functions	Serverless 函數	部署、管理 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 會：

檢查現有 Schema 避免衝突
產生完整的 SQL（含 RLS）
建立 Migration 檔案
執行 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 認證失敗

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

無法連接到專案

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

操作被拒絕

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

搭配其他 MCP

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

參考資源

下一步

Context7 MCP - 取得最新文件
Playwright MCP - 瀏覽器自動化
shadcn MCP - UI 元件查詢

Supabase MCP ​

為什麼需要 Supabase MCP？ ​

安裝方式 ​

方法 1：Claude Code CLI（推薦） ​

方法 2：手動 JSON 設定 ​

方法 3：本地開發（Supabase CLI） ​

設定選項 ​

功能群組（Feature Groups） ​

使用方式 ​

查詢 Schema ​

執行查詢 ​

建立表格與 Migration ​

產生 TypeScript 型別 ​

查看 Logs ​

安全性最佳實踐 ​

1. 不要連接 Production ​

2. 使用唯讀模式 ​

3. 限定專案範圍 ​

4. 保持工具審核 ​

5. 使用非生產資料 ​

與 Next.js 整合 ​

安裝客戶端 ​

建立客戶端 ​

環境變數 ​

查詢範例 ​

範例：建立完整的 Blog Schema ​

驗證安裝 ​

故障排除 ​

OAuth 認證失敗 ​

無法連接到專案 ​

操作被拒絕 ​

搭配其他 MCP ​

參考資源 ​

下一步 ​

Supabase MCP

為什麼需要 Supabase MCP？

安裝方式

方法 1：Claude Code CLI（推薦）

方法 2：手動 JSON 設定

方法 3：本地開發（Supabase CLI）

設定選項

功能群組（Feature Groups）

使用方式

查詢 Schema

執行查詢

建立表格與 Migration

產生 TypeScript 型別

查看 Logs

安全性最佳實踐

1. 不要連接 Production

2. 使用唯讀模式

3. 限定專案範圍

4. 保持工具審核

5. 使用非生產資料

與 Next.js 整合

安裝客戶端

建立客戶端

環境變數

查詢範例

範例：建立完整的 Blog Schema

驗證安裝

故障排除

OAuth 認證失敗

無法連接到專案

操作被拒絕

搭配其他 MCP

參考資源

下一步