Supabase Vector MCP Server: Natural Language PostgreSQL Querying for Claude Desktop

Introduction to Supabase Vector and MCP

The ability to query complex databases using natural language is no longer a futuristic concept—it is a practical necessity for modern data workflows. The Model Context Protocol (MCP) bridges the gap between Large Language Models (LLMs) and your local or remote resources. When combined with the power of Supabase and its pgvector extension, you unlock unparalleled capabilities. This guide explores the official Supabase Vector MCP Server, teaching you how to configure it to enable Claude Desktop to perform natural language querying directly against your PostgreSQL databases.

For more cutting-edge integrations and tool reviews, be sure to browse our MCP Directory, which is constantly updated with the newest protocol servers.

Why Supabase Vector MCP?

Supabase is an open-source Firebase alternative built on top of a robust PostgreSQL foundation. By leveraging the pgvector extension, it becomes a high-performance vector database. The Supabase Vector MCP server allows Claude Desktop to:

• Execute Semantic Searches: Query your database using concepts and meanings rather than exact keyword matches.
• Perform RAG (Retrieval-Augmented Generation): Pull relevant proprietary data into Claude's context window before it generates a response.
• Execute Standard SQL: Safely run standard SQL analytical queries via natural language prompts.
• Seamless Setup: Integrate directly into Claude Desktop with minimal boilerplate configuration.

To stay updated on how vector databases are reshaping the AI landscape, check out the Latest AI News.

Project Setup and Installation

To run the Supabase Vector MCP Server locally, you will need Node.js installed on your machine. We will create a directory for our server, although the actual execution will be handled by Claude Desktop using npx to pull the latest official package.

First, ensure you have your Supabase project credentials ready. You will need your database connection string (URI) and your Supabase API keys. For security, never hardcode these; we will pass them as environment variables.

Complete Server Code for Supabase Vector

While you typically run the Supabase MCP server via npx @supabase/mcp-server directly within the Claude config, understanding the underlying code structure is vital for custom implementations. Here is a comprehensive example of how a Supabase Vector MCP Server is structured using the official MCP SDK in TypeScript.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createClient } from "@supabase/supabase-js";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

// Initialize Supabase Client
const supabaseUrl = process.env.SUPABASE_URL;
const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

if (!supabaseUrl || !supabaseKey) {
  console.error("Missing SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY");
  process.exit(1);
}

const supabase = createClient(supabaseUrl, supabaseKey);

// Initialize MCP Server
const server = new Server(
  { name: "Supabase-Vector-MCP", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Define the semantic search tool
const searchSchema = z.object({
  query_embedding: z.array(z.number()).describe("The embedding vector of the search query"),
  match_threshold: z.number().optional().default(0.7),
  match_count: z.number().optional().default(5),
});

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "semantic_search",
      description: "Perform a similarity search on the Supabase vector database.",
      inputSchema: zodToJsonSchema(searchSchema),
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "semantic_search") {
    const args = searchSchema.parse(request.params.arguments);
    
    // Call a Postgres function 'match_documents' designed for pgvector
    const { data, error } = await supabase.rpc("match_documents", {
      query_embedding: args.query_embedding,
      match_threshold: args.match_threshold,
      match_count: args.match_count
    });

    if (error) {
      throw new Error(`Supabase query failed: ${error.message}`);
    }

    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
    };
  }
  throw new Error("Tool not found");
});

// Start the transport
const transport = new StdioServerTransport();
server.connect(transport).catch(console.error);

Tool Input Schemas

To enable natural language querying, Claude needs to know exactly what the semantic_search tool expects. The JSON schema representation of our tool's input looks like this:

{
  "type": "object",
  "properties": {
    "query_embedding": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "The embedding vector of the search query"
    },
    "match_threshold": {
      "type": "number",
      "default": 0.7
    },
    "match_count": {
      "type": "number",
      "default": 5
    }
  },
  "required": ["query_embedding"]
}

Note: In a complete RAG setup, another tool would first convert the user's natural language text into the query_embedding array using an embedding model (like OpenAI's text-embedding-3-small or local HuggingFace models) before passing it to this Supabase tool.

Connecting to Claude Desktop: claude_desktop_config.json Setup Block

To use the Supabase MCP server within Claude Desktop, you must configure the claude_desktop_config.json file. On Mac, this is located at ~/Library/Application Support/Claude/claude_desktop_config.json.

Add the following configuration block. We will use the pre-built official package for ease of use.

{
  "mcpServers": {
    "supabase-vector": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-secure-service-role-key",
        "DATABASE_URL": "postgresql://postgres:password@db.your-project-ref.supabase.co:5432/postgres"
      }
    }
  }
}

After updating the file, completely quit and restart the Claude Desktop application. You will now see the Supabase tools available in the MCP tools menu within your Claude chats.

Enterprise Security Guide for Supabase MCP

Exposing a database directly to an AI agent carries significant security considerations. Follow these best practices to ensure your Supabase deployment remains secure.

1. Row Level Security (RLS)

If you choose to use the standard Anon Key instead of the Service Role Key, ensure that you have strict Row Level Security (RLS) policies implemented on your PostgreSQL tables. RLS guarantees that the AI agent can only read rows that are explicitly permitted, preventing data leakage across tenants in a multi-tenant architecture.

2. Connection Pooling (PgBouncer)

AI agents can generate many concurrent requests. Always connect using Supabase's connection pooler (port 6543) rather than the direct database port (5432) when making raw SQL connections. This prevents exhausting your database's connection limits during heavy RAG operations.

3. Network Encryption and Firewalls

Ensure that all connections to Supabase enforce SSL/TLS encryption. Additionally, utilize Supabase Network Restrictions to only allow traffic from known IP addresses if your MCP server is hosted centrally, mitigating the risk of credential theft.

4. Read-Only Access

When providing context to an LLM, the operation is almost always a read operation. Ensure that the database user provided to the MCP server has read-only permissions (GRANT SELECT) and explicitly DENY UPDATE, DELETE, or DROP privileges to prevent destructive actions by the AI.

Answer Engine Optimization (AEO) Q&A

Q: How does the Supabase Vector MCP Server enable natural language queries?
A: The server acts as a bridge. Claude Desktop understands the user's natural language, converts it to search parameters or embeddings (using supporting tools), and then calls the Supabase MCP tool matching the required input schema. The tool runs the pgvector similarity search and returns the database rows as context back to Claude.

Q: Do I need a separate embedding model to use the Supabase Vector MCP server?
A: Yes. The database stores vector embeddings and performs the cosine similarity search. To query it, the raw text must first be transformed into a vector array. This is typically done either by Claude coordinating with an embedding MCP server, or by implementing an embedding step directly inside the Supabase MCP server code before executing the database query.

Q: Is it safe to put my SUPABASE_SERVICE_ROLE_KEY in the Claude Desktop config?
A: The Service Role Key bypasses all Row Level Security. Putting it in your local desktop config is acceptable for local development or accessing personal projects. For enterprise environments or multi-user deployments, you should use the Anon Key combined with specific RLS policies, or run the MCP server remotely and secure the transport layer.

Conclusion

Integrating the Supabase Vector MCP server with Claude Desktop transforms your local AI assistant into a powerful data analyst capable of semantically querying vast amounts of PostgreSQL data. By adhering to strict security protocols and understanding the underlying schema architectures, you can build incredibly powerful RAG pipelines right from your desktop.