The Supabase MCP Server enables you to connect your Supabase projects with AI assistants like Cursor, Claude, and Windsurf through the Model Context Protocol (MCP). This standardized protocol allows AI assistants to interact directly with your Supabase project to perform tasks such as managing tables, fetching configurations, and querying data.
You will need Node.js installed on your machine. You can verify your installation by running:
node -v
If Node.js is not installed, you can download it from nodejs.org.
Go to your Supabase settings and create a personal access token. Give it a descriptive name like "Cursor MCP Server".
This token will authenticate the MCP server with your Supabase account. Make sure to copy it after creation as you won't be able to view it again.
Configure your MCP client (such as Cursor) to use this server. Most MCP clients use a JSON configuration format:
{
"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 <personal-access-token>
with your token from step 1 and <project-ref>
with your project ID.
The server accepts several important configuration flags:
--read-only
: Restricts the server to read-only queries (recommended)--project-ref
: Scopes the server to a specific project (recommended)--features
: Specifies which tool groups to enableOn Windows, you'll need to prefix the command with cmd /c
:
{
"mcpServers": {
"supabase": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=<project-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
}
}
}
}
Or with wsl
if you're running Node.js inside WSL:
{
"mcpServers": {
"supabase": {
"command": "wsl",
"args": [
"npx",
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=<project-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
}
}
}
}
Ensure Node.js is available in your PATH environment variable.
Restrict the server to a specific project using the --project-ref
flag:
npx -y @supabase/mcp-server-supabase@latest --project-ref=<project-ref>
Find your Project ID in your Supabase project settings under "Project ID".
Enable read-only mode to restrict operations to read-only queries:
npx -y @supabase/mcp-server-supabase@latest --read-only
This prevents write operations by executing SQL as a read-only Postgres user.
Customize which tool groups are available to the LLM:
npx -y @supabase/mcp-server-supabase@latest --features=database,docs
Available groups include:
account
: Project and organization managementdocs
: Documentation searchdatabase
: Database operationsdebug
: Logs and advisoriesdevelopment
: Project URL, API keys, TypeScript typesfunctions
: Edge Function managementstorage
: Storage bucket managementbranching
: Database branching (requires paid plan)list_tables
: Lists all tables within specified schemaslist_extensions
: Lists all database extensionslist_migrations
: Lists all database migrationsapply_migration
: Applies SQL migrations to the databaseexecute_sql
: Executes raw SQL queriessearch_docs
: Searches Supabase documentation for up-to-date informationget_logs
: Retrieves logs by service typeget_advisors
: Gets advisory notices for security or performance issuesget_project_url
: Gets the API URL for a projectget_anon_key
: Retrieves the anonymous API keygenerate_typescript_types
: Generates TypeScript types from your schemaTo minimize risks when using the Supabase MCP server:
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "supabase" '{"command":"npx","args":["-y","@supabase/mcp-server-supabase@latest","--read-only","--project-ref=<project-ref>"],"env":{"SUPABASE_ACCESS_TOKEN":"<personal-access-token>"}}'
See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json
file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json
file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json
file will be opened and you can add your server like this:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=<project-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
}
}
}
}
To add an MCP server to a project you can create a new .cursor/mcp.json
file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.config/Claude/claude_desktop_config.json
2. Add this to your configuration file:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=<project-ref>"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
}
}
}
}
3. Restart Claude Desktop for the changes to take effect