Supabase MCP

npx add-mcp 'https://mcp.supabase.com/mcp'

Máy chủ Supabase MCP

Kết nối các dự án Supabase của bạn với Cursor, Claude, Windsurf và các trợ lý AI khác.

Giao thức Ngữ cảnh Mô hình (MCP) chuẩn hóa cách các Mô hình Ngôn ngữ Lớn (LLM) trao đổi với các dịch vụ bên ngoài như Supabase. Nó kết nối trực tiếp các trợ lý AI với dự án Supabase của bạn và cho phép chúng thực hiện các tác vụ như quản lý bảng, lấy cấu hình và truy vấn dữ liệu. Xem danh sách đầy đủ các công cụ.

Thiết lập

1. Tuân thủ các phương pháp bảo mật tốt nhất của chúng tôi

Trước khi thiết lập máy chủ MCP, chúng tôi khuyên bạn nên đọc các phương pháp bảo mật tốt nhất của chúng tôi để hiểu các rủi ro khi kết nối LLM với các dự án Supabase của bạn và cách giảm thiểu chúng.

2. Cấu hình máy khách MCP của bạn

Để cấu hình máy chủ Supabase MCP trên máy khách của bạn, hãy truy cập tài liệu thiết lập của chúng tôi. Bạn cũng có thể tạo URL MCP tùy chỉnh cho dự án của mình bằng cách truy cập tab kết nối MCP trong bảng điều khiển Supabase.

Máy khách MCP của bạn sẽ tự động nhắc bạn đăng nhập vào Supabase trong quá trình thiết lập. Hãy chắc chắn chọn tổ chức chứa dự án bạn muốn làm việc.

Hầu hết các máy khách MCP yêu cầu thông tin sau:

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

Nếu bạn không thấy máy khách MCP của mình được liệt kê trong tài liệu của chúng tôi, hãy kiểm tra tài liệu MCP của máy khách và sao chép thông tin MCP ở trên vào định dạng mong đợi của họ (json, yaml, v.v.).

CLI

Nếu bạn đang chạy Supabase cục bộ với Supabase CLI, bạn có thể truy cập máy chủ MCP tại http://localhost:54321/mcp. Hiện tại, Máy chủ MCP trong môi trường CLI cung cấp một tập hợp con giới hạn các công cụ và không có OAuth 2.1.

Tự lưu trữ

Đối với Supabase tự lưu trữ, hãy kiểm tra trang Bật máy chủ MCP. Hiện tại, Máy chủ MCP trong môi trường tự lưu trữ cung cấp một tập hợp con giới hạn các công cụ và không có OAuth 2.1.

Tùy chọn cấu hình và công cụ

Xem tài liệu Máy chủ Supabase MCP để biết danh sách đầy đủ các công cụ khả dụng và tùy chọn cấu hình.

Tài liệu cũng có trình tạo URL tương tác để điền sẵn các tùy chọn cấu hình cho bạn.

Sử dụng với Máy khách MCP của AI SDK

Gói @supabase/mcp-server-supabase xuất createToolSchemas() để điền sơ đồ đầu vào và đầu ra cho máy khách MCP của Vercel AI SDK. Điều này cho phép các công cụ Supabase MCP được xử lý như các công cụ tĩnh với xác thực phía máy khách và các kiểu TypeScript được suy luận cho đầu vào và đầu ra của chúng.

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}

createToolSchemas() chấp nhận các tùy chọn lọc tương tự như các tham số URL của máy chủ MCP:

• features: Giới hạn ở các nhóm tính năng cụ thể (ví dụ: ['database', 'docs']). Mặc định là tất cả các nhóm tính năng mặc định.
• projectScoped: Khi true, bỏ qua project_id khỏi sơ đồ đầu vào của công cụ và loại trừ các công cụ cấp tài khoản — sử dụng khi kết nối với máy chủ được cấu hình với project_ref. Mặc định là false.
• readOnly: Khi true, loại trừ các công cụ thay đổi dữ liệu — sử dụng khi kết nối với máy chủ được cấu hình với read_only=true. Mặc định là false.

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!LƯU Ý] Máy chủ này không gửi structuredContent trong kết quả công cụ MCP. AI SDK dự phòng bằng cách phân tích cú pháp JSON từ văn bản content.

Để biết thêm thông tin, hãy xem Định nghĩa Sơ đồ và Đầu ra Công cụ Được định kiểu trong tài liệu AI SDK.

Tự lưu trữ điểm cuối MCP

Gói @supabase/mcp-server-supabase xuất createSupabaseMcpHandler() để phục vụ các công cụ qua HTTP từ điểm cuối của riêng bạn. Nó chấp nhận cùng SupabaseMcpServerOptions như createSupabaseMcpServer(), quan trọng nhất là platform.

Trình xử lý chỉ nói phiên bản giao thức hiện tại. Nó được tạo với legacy: 'reject', vì vậy một máy khách chỉ nói giao thức thời đại 2025 sẽ nhận được HTTP 400 thay vì được phục vụ.

Khi platform mang thông tin xác thực theo từng yêu cầu, hãy tạo trình xử lý cho từng yêu cầu và đóng nó khi phản hồi hoàn tất. Trình xử lý bao quanh platform bạn cung cấp, vì vậy một trình xử lý dùng chung sẽ phục vụ mọi yêu cầu với nền tảng đó.

Một trình xử lý tồn tại lâu dài là phù hợp khi platform được dự định dùng chung, ví dụ như mã thông báo tài khoản dịch vụ. Tạo nó một lần và close() nó khi tắt máy thay vì cho từng phản hồi, vì close() phá hủy bộ định tuyến đăng ký và từ chối các yêu cầu sau đó.

import { createServer } from 'node:http';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase';
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api';

const server = createServer((req, res) => {
  const accessToken = getAccessTokenFromRequest(req); // your own auth

  const handler = createSupabaseMcpHandler({
    platform: createSupabaseApiPlatform({ accessToken }),
  });

  // `close()` aborts in-flight exchanges, so close on `res` finishing rather
  // than when the handler resolves, which would cut streaming responses short.
  res.on('close', () => {
    handler.close().catch((error) => console.error(error));
  });

  toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});

toNodeHandler đến từ @modelcontextprotocol/node. Mã của bạn nhập trực tiếp nó, vì vậy hãy cài đặt nó cùng với.

Khả năng quan sát

Truyền một observer cho createSupabaseMcpServer để thu thập kết quả vòng đời yêu cầu và các dữ kiện tích hợp sẵn của Supabase. Ở đây, platform là bộ điều hợp nền tảng hiện có của bạn:

import { createSupabaseMcpServer } from '@supabase/mcp-server-supabase';

const server = createSupabaseMcpServer({
  platform,
  observer: (context) => ({
    record(fact) {
      console.info(fact);
    },
    end(result) {
      console.info({ ...context, ...result });
    },
  }),
});

Máy chủ không tự động chuyển tiếp tải trọng yêu cầu hoặc phản hồi đến bộ quan sát. Các dữ kiện tích hợp sẵn của Supabase sử dụng một tập hợp đóng các trường và giá trị có giới hạn; các dữ kiện tùy chỉnh không nhận được xác thực quyền riêng tư tự động. Bỏ qua observer sẽ bỏ qua tất cả công việc quan sát. Các lỗi của bộ quan sát, bộ phân loại và bộ thu không thay đổi hành vi yêu cầu, nhưng công việc đồng bộ của bộ quan sát và bộ phân loại có thể chặn các yêu cầu.

Các máy chủ MCP khác

@supabase/mcp-server-postgrest

Máy chủ MCP PostgREST cho phép bạn kết nối người dùng của riêng mình với ứng dụng của bạn qua REST API. Xem thêm chi tiết trong README dự án của nó.

Tài nguyên

• Giao thức Ngữ cảnh Mô hình: Tìm hiểu thêm về MCP và các khả năng của nó.
• Từ phát triển đến sản xuất: Tìm hiểu cách thúc đẩy các thay đổi một cách an toàn đến môi trường sản xuất.

Dành cho nhà phát triển

Xem CONTRIBUTING để biết chi tiết về cách đóng góp cho dự án này.

Giấy phép

Dự án này được cấp phép theo Apache 2.0. Xem tệp LICENSE để biết chi tiết.