← All connection guides

How to connect Claude Code to Supabase

Connect Claude Code to Supabase MCP with one project and read-only access, then verify a real database read.

Free guide · Updated

Based on official documentation · Checked

Ask your agent

Copy the prompt and paste it into your assistant.

Quick answer

Add the hosted Supabase MCP server to Claude Code, scope it to a test project, enable read-only access and complete OAuth. This gives the assistant tools for the selected project; it is different from installing the Supabase SDK in your application.

Before you start

Choose a development project containing no production secrets or personal data. Record the project reference and intended organization. Use a current Claude Code client that supports the vendor’s connection method. A database password or service-role key should not be pasted into the conversation.

1. Configure a scoped read-only server

In the Supabase MCP setup documentation, select the intended project, Claude Code and read-only mode. The documented URL parameters can combine project_ref and read_only=true. Replace YOUR_PROJECT_REF below with the actual project reference, preserving the quoted URL.

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"

2. Review configuration scope

The command uses project scope, which may store server configuration in a project file shared with teammates. A project reference is not an access token; nevertheless review the generated configuration before committing it, especially if other custom headers are present.

3. Authenticate

In a regular terminal, start Claude Code and open /mcp. Select supabase and complete Authenticate in the browser. Choose the organization containing the test project. Do not assume the account from an unrelated dashboard session is the one the client authorized.

claude /mcp

Practice

4. Verify project access

  1. Ask Claude Code to use Supabase MCP to list tables in the selected test project and read a few neutral rows from one known test table. Compare the table identity and values with the dashboard.

Output: Correct project, table and test data returned through MCP; a read-only configuration is present and no mutation was requested.

5. Confirm the boundary

Read-only mode should not be interpreted as eliminating every security risk from connecting an assistant. Avoid testing restrictions by running a destructive query. Restart the client and repeat a harmless read using the same project scope.

Troubleshooting

Wrong project: inspect project_ref and the approved organization. Missing tools: review enabled feature groups and reload the connection. Authorization failure: inspect the OAuth result before trying a PAT fallback. An empty table and a failed query are different outcomes; retain the exact error privately rather than inventing a successful example.

Disconnect and limits

Remove the test server configuration from Claude Code and revoke its OAuth grant if appropriate. Review any shared project configuration before removal. This guide uses a hosted Supabase development project with read-only access. Local Supabase and unattended CI use different connection details.

Sources

Read the primary material