supabase-postgres-mcp
Provides tools for inspecting and querying PostgreSQL databases via a connection string, including schema/table discovery, table descriptions, read-only SQL queries, and optional write execution.
Allows inspecting and querying a Supabase Postgres database, including listing schemas and tables, describing table structures, and running read-only SQL queries; optional write execution can be enabled.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
supabase-postgres-mcp
A FastMCP server that lets MCP clients (Claude Desktop, VS Code, Cursor, OpenCode, ...) inspect and query a Supabase Postgres database.
One setting to configure: a Postgres connection string (
DATABASE_URL).Read-only by default.
SELECT,WITH,SHOW, andEXPLAINrun inside a read-only transaction. Writes require an explicit opt-in at startup.Supabase-aware.
sslmode=require(what the Supabase dashboard emits) is handled by libpq, TLS is enabled automatically for Supabase hosts, and prepared statements are disabled for Supavisor/PgBouncer compatibility.$1placeholders. The tool API accepts Supabase-style$1, $2, ...parameters (translated safely for psycopg);%s-style SQL also works.Starts without a connection string so clients can always connect; tool calls then return an actionable error instead of crashing the process.
Guarded execution. One statement per call, transaction-control and
COPYstatements rejected, statement timeout, and a row cap.
Tools
Tool | Writes | Description |
| no | List non-system schemas (usually |
| no | List tables/views in a schema with their comments. |
| no | Columns, types, primary key, foreign keys, indexes, comment. |
| no | Run one read-only SQL statement with |
| yes | Run one |
query results look like:
{
"status": "SELECT 42",
"row_count": 42,
"returned_rows": 42,
"truncated": false,
"max_rows": 100,
"duration_ms": 12,
"fields": [{ "name": "id", "type_code": 23 }],
"rows": [{ "id": 1 }]
}row_count is what Postgres reports; returned_rows is what was sent back.
truncated is true when more rows existed than max_rows allowed. Add a
LIMIT to your SQL when you expect large result sets.
Values are JSON-normalized for MCP: numeric/int8 become strings, dates and
timestamps become ISO-8601 strings, bytea becomes base64, and duplicate column
names are suffixed (id, id_2).
Related MCP server: postgres-mcp-server
Quick start
git clone https://github.com/d-manoharan/mcp-server-test.git
cd mcp-server-test
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env
# edit .env and replace the DATABASE_URL placeholder
pytest -q # optional: smoke tests need no databaseThen point your MCP client at .venv/bin/supabase-postgres-mcp (see below), or
run it manually:
python -m supabase_postgres_mcpThe server speaks MCP over stdio, so it will appear to hang when run in a terminal. That is expected — normally your MCP client launches it.
Using uv (optional)
uv sync
uv run supabase-postgres-mcpThe connection string
Copy it from Supabase Dashboard → Project Settings → Database → Connection string. Replace only the placeholders:
DATABASE_URL=postgresql://postgres.<PROJECT_REF>:<YOUR_DB_PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=requireThree forms are supported:
Mode | Port | Host | Notes |
Transaction pooler |
|
| Recommended. IPv4-compatible, good for short-lived MCP processes. No session-level features ( |
Session pooler |
|
| IPv4-compatible with session-level features. |
Direct |
|
| IPv6-only by default; use only if your network supports IPv6. |
Tips:
The pooler username is
postgres.<PROJECT_REF>, not justpostgres.URL-encode special characters in the password:
p@ss→p%40ss,#→%23.Keep
?sslmode=require(orverify-fullif you want certificate verification). If you omit it on a Supabase host, TLS is enabled automatically.Prisma-style parameters such as
?pgbouncer=true&connection_limit=1are dropped automatically because libpq does not understand them.
The server loads .env from the current directory or from next to
pyproject.toml. Real environment variables always win, so client config takes
precedence over the file.
MCP client configuration
Replace /absolute/path/to/mcp-server-test with the real path.
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"supabase-postgres": {
"command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
"env": {
"DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
}
}
}
}VS Code
.vscode/mcp.json:
{
"servers": {
"supabase-postgres": {
"type": "stdio",
"command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
"env": {
"DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
}
}
}
}OpenCode
opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"supabase-postgres": {
"type": "local",
"command": ["/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp"],
"enabled": true,
"environment": {
"DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
}
}
}
}Cursor
.cursor/mcp.json:
{
"mcpServers": {
"supabase-postgres": {
"command": "/absolute/path/to/mcp-server-test/.venv/bin/supabase-postgres-mcp",
"env": {
"DATABASE_URL": "postgresql://postgres.<PROJECT_REF>:<PASSWORD>@aws-0-<REGION>.pooler.supabase.com:6543/postgres?sslmode=require"
}
}
}
}If you prefer not to put the URL in client config, copy .env.example to
.env next to pyproject.toml and omit the env block.
Configuration
Variable | Default | Description |
| — | Supabase Postgres connection string. Also accepts |
|
| Set to |
|
| Default row cap for |
|
| Server-side statement timeout (1000–120000). |
|
| Maximum pooled connections (1–20). |
|
| TCP connect timeout (1–60). |
|
| Shown in |
| unset | Set to |
| unset | Explicit |
Safety
Every
queryruns inBEGIN+SET TRANSACTION READ ONLYand is rolled back (force_rollback=True). Postgres rejects writes with25006 read_only_sql_transaction.Only one statement per call is allowed. Strings, quoted identifiers, dollar-quoted bodies, and comments are understood by the splitter, so a payload such as
COMMIT; DELETE ...is rejected.BEGIN/COMMIT/ROLLBACK/SAVEPOINTandCOPYare blocked explicitly.executeis not registered unlessALLOW_WRITES=true, and it commits immediately. There is no preview or undo.The server connects with the role in
DATABASE_URL. Connecting aspostgresbypasses Row Level Security. For read-only usage, prefer a dedicated role:create role mcp_reader login password '<strong-password>'; grant usage on schema public to mcp_reader; grant select on all tables in schema public to mcp_reader; alter default privileges in schema public grant select on tables to mcp_reader;Then use
postgresql://mcp_reader.<PROJECT_REF>:<password>@...(pooler) orpostgresql://mcp_reader:<password>@db.<PROJECT_REF>.supabase.co:5432/postgres.Passwords placed in
.envor client config are stored in plain text. Keep.envout of version control (it is git-ignored) and rotate credentials if they leak.
Troubleshooting
Symptom | Likely fix |
| Set it in the client config, the shell, or |
| Use the pooler host ( |
| Username must be |
| Re-copy the password; URL-encode special characters. |
| Remove |
| Remove unsupported URL parameters, or open an issue; common Prisma parameters are already stripped. |
| Use |
| The server already disables prepared statements for the pooler. If you use another client, set |
| Send one statement per tool call. |
Development
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -q
TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres \
python scripts/integration.pyThe integration test creates a mcp_it_* schema, exercises every tool, and
drops the schema. Run it against a disposable database, never production.
Layout
src/supabase_postgres_mcp/
config.py environment parsing and .env loading
db.py pool, TLS defaults, read-only/write execution
sql.py single-statement validation and $n parameter binding
server.py FastMCP server and tool definitions
tests/ unit and smoke tests (no database required)
scripts/ integration test against a real databaseLimitations
stdio transport only (no HTTP).
No migration, schema-editing, or Supabase Management API features; this is a focused SQL access server.
libpq buffers each result, so the row cap limits what is returned but not what the server sends over the wire. Use
LIMITfor very large tables; the statement timeout is the backstop.Transaction pooler connections cannot keep session state between calls.
COPYis not supported.ALLOW_WRITESis read at startup; restart the server after changing it.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.
MCP server for interacting with the Supabase platform
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables querying and modifying PostgreSQL databases through MCP tools with read/write operations, schema inspection, and write-safety constraints that limit modifications to the mcp schema.1-
- AlicenseNot gradedqualityDmaintenanceEnables inspecting database schemas and executing read-only SQL queries on a PostgreSQL database via MCP tools.5 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to PostgreSQL databases via MCP, enforcing least-privilege roles, row-level security, masked views, and SQL AST guardrails to prevent data leakage and unauthorized operations, enabling AI agents to safely query sensitive production data.MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to safely query one or more PostgreSQL databases with read-only tools and explicitly approved write operations.1-