Query MCP Server

Overview

The Query MCP server is an open‑source bridge that lets developers run SQL queries, manage database schemas, and interact with Supabase’s Management API directly from AI assistants such as Claude. By exposing a Model Context Protocol (MCP) interface, it removes the need for custom integrations between an assistant and a Supabase project. The server adds safety controls that prevent accidental data loss or destructive operations, making it suitable for both exploratory development and production workflows.

What problem does it solve?

When building AI‑powered tools that query or mutate a Supabase database, developers typically have to write bespoke code for authentication, connection pooling, and query validation. The Query MCP server abstracts these concerns into a single, well‑defined protocol. It allows an assistant to ask for a schema change or run a SELECT statement without the developer writing boilerplate code, while still enforcing read‑only or destructive safeguards. This reduces friction for rapid prototyping and ensures that all operations pass through a controlled, auditable channel.

Core capabilities

• Safe SQL execution – The server supports three safety tiers: safe (read‑only), write, and destructive. Each tier is enforced at runtime, preventing accidental schema changes or data deletions unless explicitly permitted.
• Runtime query validation – Before execution, queries are parsed and assessed for risk level. This prevents malformed or potentially harmful statements from reaching the database.
• Transaction handling – Whether using direct connections or connection pools, the server guarantees atomicity and isolation for complex operations.
• Schema versioning – Every change to the database schema is automatically recorded, enabling rollbacks and audit trails.
• Supabase API integration – Beyond raw SQL, the server exposes the Supabase Management API and Auth Admin SDK, allowing assistants to create projects, manage users, or modify storage buckets through simple MCP calls.
• Tool support for popular clients – Built‑in tools streamline use with Cursor, Windsurf, and Cline, providing pre‑configured prompts and response formats that fit those environments.

Use cases

• AI‑driven database design – A developer can ask an assistant to add a new column or table, and the server will validate, execute, and record the change.
• Automated data cleanup – An assistant can schedule safe queries to archive old records, with the server ensuring that no destructive commands slip through.
• Project provisioning – Using the Supabase Management API, an assistant can spin up new projects or adjust project settings on demand.
• User management – The Auth Admin SDK lets assistants create, update, or delete users without exposing sensitive credentials.
• Rapid prototyping – During feature development, a team can experiment with queries or schema tweaks in real time, confident that the server’s safety layers will protect production data.

Integration with AI workflows

The MCP interface is language‑agnostic, so any AI assistant that implements the standard protocol can connect to Query MCP. Once connected, the assistant can issue commands such as “run this SELECT” or “create a new table named .” The server replies with structured results, including execution time, affected rows, and any error messages. This tight coupling enables assistants to provide instant feedback, suggest optimizations, or automatically generate migration scripts—all within the same conversational loop.

Standout advantages

• Zero‑config safety – The built‑in risk assessment and tiered permissions mean developers don’t have to remember to set or guard against destructive statements manually.
• Unified API surface – One server handles both raw SQL and Supabase’s higher‑level APIs, reducing the number of moving parts in a developer’s stack.
• Open source and community‑driven – With over 17 k PyPI installs, the server has proven reliability and a growing ecosystem of contributors.
• Python 3.12+ support – Leveraging modern async features, the server offers high performance and minimal resource overhead.

In summary, Query MCP turns Supabase into a fully controllable, AI‑friendly data layer. By combining robust safety mechanisms with comprehensive API exposure, it empowers developers to build intelligent assistants that can query, modify, and manage their databases confidently and efficiently.