mirror of
https://github.com/supabase/supabase.git
synced 2026-10-15 14:19:11 +03:00
Burke Holland
84c4bbb32e
* fix: update installation links for VS Code and VS Code Insiders in MCP guide * Add insiders quality param
234 lines
10 KiB
Plaintext
234 lines
10 KiB
Plaintext
---
|
|
id: 'ai-tools-mcp'
|
|
title: 'Model context protocol (MCP)'
|
|
subtitle: 'Connect your AI tools to Supabase using MCP'
|
|
description: 'Connect your AI tools to Supabase using MCP'
|
|
sidebar_label: 'Model context protocol (MCP)'
|
|
---
|
|
|
|
The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Supabase. This guide covers how to connect Supabase to the following AI tools using MCP:
|
|
|
|
- [Cursor](#cursor)
|
|
- [Windsurf](#windsurf) (Codium)
|
|
- [Visual Studio Code](#visual-studio-code-copilot) (Copilot)
|
|
- [Cline](#cline) (VS Code extension)
|
|
- [Claude desktop](#claude-desktop)
|
|
- [Claude code](#claude-code)
|
|
- [Amp](#amp)
|
|
|
|
Once connected, your AI assistants can interact with and query your Supabase projects on your behalf.
|
|
|
|
## Step 1: Create a personal access token (PAT)
|
|
|
|
First, go to your [Supabase settings](https://supabase.com/dashboard/account/tokens) and create a personal access token. Give it a name that describes its purpose, like "Cursor MCP Server". This will be used to authenticate the MCP server with your Supabase account.
|
|
|
|
## Step 2: Configure in your AI tool
|
|
|
|
MCP compatible tools can connect to Supabase using the [Supabase MCP server](https://github.com/supabase-community/supabase-mcp).
|
|
|
|
Follow the instructions for your AI tool to connect the Supabase MCP server. The configuration below uses read-only, project-scoped mode by default. We recommend these settings to prevent the agent from making unintended changes to your database. Note that read-only mode applies only to database operations. Write operations on project-management tools, such as `create_project`, are still available.
|
|
|
|
### Cursor
|
|
|
|
1. Open [Cursor](https://www.cursor.com/) and create a `.cursor` directory in your project root if it doesn't exist.
|
|
1. Create a `.cursor/mcp.json` file if it doesn't exist and open it.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "Cursor" }} />
|
|
|
|
1. Save the configuration file.
|
|
|
|
1. Open Cursor and navigate to **Settings/MCP**. You should see a green active status after the server is successfully connected.
|
|
|
|
### Windsurf
|
|
|
|
1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant.
|
|
1. Tap on the hammer (MCP) icon, then **Configure** to open the configuration file.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "Windsurf" }} />
|
|
|
|
1. Save the configuration file and reload by tapping **Refresh** in the Cascade assistant.
|
|
|
|
1. You should see a green active status after the server is successfully connected.
|
|
|
|
### Visual Studio Code (Copilot)
|
|
|
|
<div className="mb-8 not-prose [&>p]:flex [&>p]:flex-col [&>p]:gap-2">
|
|
[](https://insiders.vscode.dev/redirect/mcp/install?name=supabase&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22supabase-access-token%22%2C%22description%22%3A%22Supabase%20personal%20access%20token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40supabase%2Fmcp-server-supabase%40latest%22%2C%22--readonly%22%2C%22--project-ref%3D%24SUPABASE_MCP_PROJECT_REF%22%5D%2C%22env%22%3A%7B%22SUPABASE_ACCESS_TOKEN%22%3A%22%24%7Binput%3Asupabase-access-token%7D%22%2C%22SUPABASE_MCP_PROJECT_REF%22%3A%22%24%7Binput%3Asupabase-project-ref%7D%22%7D%7D)
|
|
[](https://insiders.vscode.dev/redirect/mcp/install?name=supabase&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22supabase-access-token%22%2C%22description%22%3A%22Supabase%20personal%20access%20token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40supabase%2Fmcp-server-supabase%40latest%22%2C%22--readonly%22%2C%22--project-ref%3D%24SUPABASE_MCP_PROJECT_REF%22%5D%2C%22env%22%3A%7B%22SUPABASE_ACCESS_TOKEN%22%3A%22%24%7Binput%3Asupabase-access-token%7D%22%2C%22SUPABASE_MCP_PROJECT_REF%22%3A%22%24%7Binput%3Asupabase-project-ref%7D%22%7D%7D&quality=insiders)
|
|
</div>
|
|
|
|
1. Open [VS Code](https://code.visualstudio.com/) and create a `.vscode` directory in your project root if it doesn't exist.
|
|
1. Create a `.vscode/mcp.json` file if it doesn't exist and open it.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_vscode_config.mdx" />
|
|
|
|
1. Save the configuration file.
|
|
1. Open Copilot chat and switch to "Agent" mode. You should see a tool icon that you can tap to confirm the MCP tools are available. Once you begin using the server, you will be prompted to enter your personal access token. Enter the token that you created earlier.
|
|
|
|
For more info on using MCP in VS Code, see the [Copilot documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
|
|
|
|
### Cline
|
|
|
|
1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon.
|
|
1. Tap **Configure MCP Servers** to open the configuration file.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "VS Code" }} />
|
|
|
|
1. Save the configuration file. Cline should automatically reload the configuration.
|
|
|
|
1. You should see a green active status after the server is successfully connected.
|
|
|
|
### Claude desktop
|
|
|
|
1. Open [Claude desktop](https://claude.ai/download) and navigate to **Settings**.
|
|
1. Under the **Developer** tab, tap **Edit Config** to open the configuration file.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "Claude desktop" }} />
|
|
|
|
1. Save the configuration file and restart Claude desktop.
|
|
|
|
1. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available.
|
|
|
|
### Claude code
|
|
|
|
You can add the Supabase MCP server to Claude Code in two ways:
|
|
|
|
#### Option 1: Project-scoped server (via .mcp.json file)
|
|
|
|
1. Create a `.mcp.json` file in your project root if it doesn't exist.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "Claude code" }} />
|
|
|
|
1. Save the configuration file.
|
|
|
|
1. Restart [Claude code](https://claude.ai/code) to apply the new configuration.
|
|
|
|
#### Option 2: Locally-scoped server (via CLI command)
|
|
|
|
You can also add the Supabase MCP server as a locally-scoped server, which will only be available to you in the current project:
|
|
|
|
1. Run the following command in your terminal:
|
|
|
|
```bash
|
|
claude mcp add supabase -s local -e SUPABASE_ACCESS_TOKEN=your_token_here -- npx -y @supabase/mcp-server-supabase@latest
|
|
```
|
|
|
|
Locally-scoped servers take precedence over project-scoped servers with the same name and are stored in your project-specific user settings.
|
|
|
|
### Amp
|
|
|
|
You can add the Supabase MCP server to Amp in two ways:
|
|
|
|
#### Option 1: VSCode settings.json
|
|
|
|
1. Open "Preferences: Open User Settings (JSON)"
|
|
2. Add the following configuration:
|
|
|
|
```json
|
|
{
|
|
"amp.mcpServers": {
|
|
"supabase": {
|
|
"command": "npx",
|
|
"args": [
|
|
"-y",
|
|
"@supabase/mcp-server-supabase@latest",
|
|
"--read-only",
|
|
"--project-ref=<project-ref>"
|
|
],
|
|
"env": {
|
|
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace `project-ref` and `personal-access-token` with your project ref and personal access token.
|
|
|
|
3. Save the configuration file.
|
|
4. Restart VS Code to apply the new configuration.
|
|
|
|
#### Option 2: Amp CLI
|
|
|
|
1. Edit `~/.config/amp/settings.json`
|
|
1. Add the following configuration:
|
|
|
|
```json
|
|
{
|
|
"amp.mcpServers": {
|
|
"supabase": {
|
|
"command": "npx",
|
|
"args": [
|
|
"-y",
|
|
"@supabase/mcp-server-supabase@latest",
|
|
"--read-only",
|
|
"--project-ref=<project-ref>"
|
|
],
|
|
"env": {
|
|
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace `project-ref` and `personal-access-token` with your project ref and personal access token.
|
|
|
|
1. Save the configuration file.
|
|
1. Restart Amp to apply the new configuration.
|
|
|
|
### Qodo Gen
|
|
|
|
1. Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ.
|
|
1. Click `Connect more tools`.
|
|
1. Click `+ Add new MCP`.
|
|
1. Add the following configuration:
|
|
|
|
<$Partial path="mcp_supabase_config.mdx" variables={{ "app": "Qodo Gen" }} />
|
|
|
|
1. Click `Save`.
|
|
|
|
### Next steps
|
|
|
|
Your AI tool is now connected to Supabase using MCP. Try asking your AI assistant to create a new project, create a table, or fetch project config.
|
|
|
|
For a full list of tools available, see the [GitHub README](https://github.com/supabase-community/supabase-mcp#tools). If you experience any issues, [submit an bug report](https://github.com/supabase-community/supabase-mcp/issues/new?template=1.Bug_report.md).
|
|
|
|
## MCP for local Supabase instances
|
|
|
|
The Supabase MCP server connects directly to the cloud platform to access your database. If you are running a local instance of Supabase, you can instead use the [Postgres MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) to connect to your local database. This MCP server runs all queries as read-only transactions.
|
|
|
|
### Step 1: Find your database connection string
|
|
|
|
To connect to your local Supabase instance, you need to get the connection string for your local database. You can find your connection string by running:
|
|
|
|
```shell
|
|
supabase status
|
|
```
|
|
|
|
or if you are using `npx`:
|
|
|
|
```shell
|
|
npx supabase status
|
|
```
|
|
|
|
This will output a list of details about your local Supabase instance. Copy the `DB URL` field in the output.
|
|
|
|
### Step 2: Configure the MCP server
|
|
|
|
Configure your client with the following:
|
|
|
|
<$Partial path="mcp_postgres_config.mdx" variables={{ "app": "your MCP client" }} />
|
|
|
|
### Next steps
|
|
|
|
Your AI tool is now connected to your local Supabase instance using MCP. Try asking the AI tool to query your database using natural language commands.
|