mcp-backend
Supports S3-compatible storage including MinIO for file upload, download, and bucket management.
Provides direct PostgreSQL access for querying, executing SQL, managing tables, and analyzing schema.
Integrates with Supabase for storage operations (buckets, files) and RLS-aware SQL execution.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-backend show me all tables"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚠️ Active Development — APIs and tools may change without prior notice. Use tagged releases (
vX.Y.Z) for stability.
Local MCP server compatible with any studio-based AI client. Provides direct PostgreSQL access, storage operations (Supabase or S3), Iceberg catalog queries and SQL seed management.
Stack
Database: PostgreSQL via
pg(direct connection)Storage: Supabase Storage or S3-compatible (MinIO, RustFS, SeaweedFS, AWS)
Data Lake: Apache Iceberg REST Catalog
Protocol: MCP over stdio
Related MCP server: mcp-database
Tools (32 Total)
Database (5)
Tool | Description |
| Run SELECT queries on PostgreSQL |
| Execute arbitrary SQL (INSERT/UPDATE/DELETE) with transaction support |
| Execute SQL file content (PL/pgSQL blocks, multi-statement scripts) with transaction support |
| Execute SQL with RLS context (impersonate user role — supabase mode only) |
| List all public tables |
Seeds (4)
Tool | Description |
| List available SQL seed files in |
| Run base seed files (languages, countries, settings, navigation) |
| Run data seed files (users, products, courses, articles) |
| Run base + data seeds in order |
Storage (11)
Tool | Description |
| List all storage buckets |
| List files in a bucket with pagination |
| Generate a signed URL for a file (private buckets) |
| Get the public URL for a file (public buckets) |
| Upload a file to a bucket with MIME type detection |
| Delete a file from a bucket |
| Download files from storage to local buckets/ folder (all buckets, one bucket, specific folder, or single file) |
| Upload multiple files or entire folder with selective file extension filtering (e.g., ignore |
| Create, update, empty or delete a storage bucket |
| Generate signed URL and atomically update DB table with URL + expiration timestamp |
Iceberg (3)
Tool | Description |
| List foreign tables in the |
| SELECT from an Iceberg foreign table via Postgres FDW with filters |
| List tables from the Iceberg REST Catalog directly |
RPC (1)
Tool | Description |
| Call a PostgreSQL RPC function with named arguments |
Bootstrap (1)
Tool | Description |
| Bootstrap Iceberg schema and foreign data wrapper |
Schema & Query Analysis (4)
Tool | Description |
| Describe table schema (columns, types, constraints, indexes) |
| Get column statistics (cardinality, NULL%, data distribution) |
| Parse SQL without executing to catch syntax errors |
| Run query with EXPLAIN ANALYZE for performance debugging |
Observability (3)
Tool | Description |
| List long-running queries with duration and state |
| Table sizes, row counts, and growth metrics |
| List indexes with size, scan count, and usage stats |
Setup
See INSTALL.md for full setup instructions.
cp .env.example .env # fill in your credentials
pnpm install
pnpm start # start MCP serverSeed structure
Seeds are organized in two directories (not committed — client-specific):
base/ ← company info, languages, countries, currencies, navigation, SEO
data/ ← users, products, courses, articles, pagesRun order: base/ always before data/.
Environment variables
Variable | Description |
|
|
| PostgreSQL connection string |
| Supabase project URL (required in supabase mode) |
| Supabase anon/publishable key (supabase mode) |
| Supabase service role key (supabase mode) |
| S3-compatible endpoint (required in postgres mode) |
| S3 access key (postgres mode) |
| S3 secret key (postgres mode) |
| Default S3 bucket name (postgres mode) |
| S3 region (default: |
| Iceberg REST Catalog URI |
| Bearer token for Iceberg catalog |
| Iceberg warehouse name |
| Iceberg namespace (default: |
| S3-compatible access key |
| S3-compatible secret key |
| S3-compatible endpoint URL |
Community
Contributions are subject to natuleadan review policies and terms.
Thanks to all contributors:
Star History
License
MIT © Leonardo Jara
Available Tools
31 toolsactive_queriesC
List active/long-running queries with details (duration, memory, locks)
Inputs: min_duration_ms.
bootstrap_icebergA
Bootstrap the Iceberg FDW on Postgres: creates namespace + tables in catalog, configures FDW server, maps foreign tables, and verifies connection.
Inputs: dry_run.
bulk_upload_filesB
Upload multiple local files to storage with optional filtering by file type. Can upload individual files or an entire folder with selective file extensions.
Inputs: bucket (required), files, folder_path, storage_prefix, +2 more.
call_rpcA
Call a Supabase PostgreSQL function (RPC) via the REST API. Uses service_role — bypasses RLS.
Inputs: fn (required), args.
column_statsA
Get column statistics: cardinality, NULL count, data distribution
Inputs: table (required), column, limit.
database_statsC
Database statistics: table sizes, row counts, growth metrics
Inputs: top_n.
delete_fileB
Delete a file from a storage bucket
Inputs: bucket (required), path (required).
download_bucketA
Download files from Supabase storage to local buckets/ folder. Can download all buckets, one bucket, a specific folder, or a single file.
Inputs: bucket, folder, file, limit.
execute_rls_sqlA
Run a SELECT query impersonating a user role (applies RLS). Useful to test what a role can see. Only available in supabase mode.
Inputs: sql (required), role (required), user_id, params.
execute_sqlA
Run any SQL statement (INSERT, UPDATE, DELETE, SELECT, etc.) with full bypass of RLS. Use with care.
Inputs: sql (required), params.
execute_sql_fileB
Execute SQL file content (PL/pgSQL blocks, multi-statement scripts). Pass raw SQL from file as string.
Inputs: sql (required), filename.
generate_and_update_signed_urlA
Generate a signed URL for a private bucket file and update the URL in a DB media table
Inputs: bucket (required), path (required), table (required), id_value (required), +4 more.
get_public_urlA
Get the public URL for a file in a public bucket
Inputs: bucket (required), path (required).
get_signed_urlB
Generate a signed URL for a private bucket file
Inputs: bucket (required), path (required), expires_in.
index_infoC
List indexes with size, scan count, and usage stats
Inputs: table.
list_bucketsA
List all Supabase storage buckets with their visibility
Inputs: no named parameters.
list_filesB
List files in a bucket folder
Inputs: bucket (required), folder, limit.
list_iceberg_catalog_tablesC
List tables directly from the Iceberg REST Catalog (requires CATALOG_URI + AWS credentials)
Inputs: namespace.
list_iceberg_tablesA
List all foreign tables in the iceberg schema (mapped via FDW in Postgres)
Inputs: no named parameters.
list_seed_filesB
Lists all SQL files available in base/ and data/
Inputs: target.
list_tablesA
List all tables in the public schema
Inputs: no named parameters.
manage_bucketB
Create, update, delete or empty a storage bucket. Works with Supabase Storage (supabase mode) or S3-compatible (postgres mode).
Inputs: action (required), name (required), public, allowed_mime_types, +1 more.
query_dbA
Run a raw SQL SELECT query against the database. READ ONLY - for inspection/verification.
Inputs: sql (required), params.
query_icebergB
SELECT from an Iceberg foreign table via Postgres FDW (e.g. 'iceberg.aud_analytics_lake')
Inputs: table (required), where, order_by, limit.
query_with_explainA
Run query with EXPLAIN ANALYZE for performance debugging
Inputs: sql (required), verbose.
run_all_seedsB
Runs base seed then data seed in order
Inputs: no named parameters.
run_base_seedA
Runs all SQL files in base/ (02-base equivalent with real natuleadan company data)
Inputs: no named parameters.
run_data_seedB
Runs all SQL files in data/ (03-data.ee equivalent with real users, products, courses)
Inputs: no named parameters.
table_infoB
Describe table schema: columns, types, constraints, indexes
Inputs: table (required).
upload_fileB
Upload any local file to a storage bucket. local_path can be absolute (/Users/...) or relative to buckets/{bucket}/
Inputs: bucket (required), local_path (required), storage_path (required), upsert.
validate_sqlA
Parse SQL without executing - catch syntax errors early
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools have distinct purposes, but there is some overlap between execute_sql, query_db, and execute_rls_sql, as well as between upload_file and bulk_upload_files. However, descriptions clarify the differences, making ambiguity low overall.
The majority of tools follow a verb_noun pattern (e.g., bootstrap_iceberg, delete_file). A few, like active_queries and column_stats, deviate slightly, but the overall convention is consistent and predictable.
With 31 tools, the count is on the higher side but still reasonable given the broad scope covering database operations, storage, Iceberg, seeding, and RPC. Each tool serves a specific purpose, and the number is appropriate for the server's domain.
The tool set covers most essential operations for a backend/database server: SQL execution, storage management, Iceberg integration, seeding, and RPC calls. Missing are explicit schema modification tools, but those can be done via execute_sql. Overall, the surface is comprehensive.
Maintenance
Related MCP Connectors
MCP server for interacting with the Supabase platform
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server with 32 tools for ETL ingestion, AI-generated data quality rules, AI transformations, vector search, and natural-language SQL. Works across Postgres, MongoDB, Kafka, S3/MinIO, HashiCorp Vault, and five vector stores (Qdrant, Weaviate, Milvus, Chroma, pgvector).9014Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for connecting to databases (PostgreSQL, MySQL, SQL Server, Redis) enabling SQL queries, table exploration, and Redis key-value operations.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Supabase, enabling database CRUD, storage management, auth administration, project management, edge functions, and secrets via 31 tools.9 npmMIT
- AlicenseNot gradedqualityFmaintenanceMCP server for self-hosted Supabase with RLS-aware PostgreSQL and PostgREST layers, enabling safe database introspection, SQL queries, and PostgREST access via natural language.MIT