mcp-backend

MCP server with full backend access — PostgreSQL, Storage (Supabase or S3), Iceberg and seeds

⚠️ 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

---

Tools (32 Total)

Database (5)

Tool	Description
query_db	Run SELECT queries on PostgreSQL
execute_sql	Execute arbitrary SQL (INSERT/UPDATE/DELETE) with transaction support
execute_sql_file	Execute SQL file content (PL/pgSQL blocks, multi-statement scripts) with transaction support
execute_rls_sql	Execute SQL with RLS context (impersonate user role — supabase mode only)
list_tables	List all public tables

Seeds (4)

Tool	Description
list_seed_files	List available SQL seed files in base/ and data/
run_base_seed	Run base seed files (languages, countries, settings, navigation)
run_data_seed	Run data seed files (users, products, courses, articles)
run_all_seeds	Run base + data seeds in order

Storage (11)

Tool	Description
list_buckets	List all storage buckets
list_files	List files in a bucket with pagination
get_signed_url	Generate a signed URL for a file (private buckets)
get_public_url	Get the public URL for a file (public buckets)
upload_file	Upload a file to a bucket with MIME type detection
delete_file	Delete a file from a bucket
download_bucket	Download files from storage to local buckets/ folder (all buckets, one bucket, specific folder, or single file)
bulk_upload_files	Upload multiple files or entire folder with selective file extension filtering (e.g., ignore .sql, .tmp) and optional storage prefix
manage_bucket	Create, update, empty or delete a storage bucket
generate_and_update_signed_url	Generate signed URL and atomically update DB table with URL + expiration timestamp

Iceberg (3)

Tool	Description
list_iceberg_tables	List foreign tables in the iceberg schema (via FDW)
query_iceberg	SELECT from an Iceberg foreign table via Postgres FDW with filters
list_iceberg_catalog_tables	List tables from the Iceberg REST Catalog directly

RPC (1)

Tool	Description
call_rpc	Call a PostgreSQL RPC function with named arguments

Bootstrap (1)

Tool	Description
bootstrap_iceberg	Bootstrap Iceberg schema and foreign data wrapper

Schema & Query Analysis (4)

Tool	Description
table_info	Describe table schema (columns, types, constraints, indexes)
column_stats	Get column statistics (cardinality, NULL%, data distribution)
validate_sql	Parse SQL without executing to catch syntax errors
query_with_explain	Run query with EXPLAIN ANALYZE for performance debugging

Observability (3)

Tool	Description
active_queries	List long-running queries with duration and state
database_stats	Table sizes, row counts, and growth metrics
index_info	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 server

---

Seed structure

Seeds are organized in two directories (not committed — client-specific):

base/   ← company info, languages, countries, currencies, navigation, SEO
data/   ← users, products, courses, articles, pages

Run order: base/ always before data/.

---

Environment variables

Variable	Description
BACKEND_MODE	supabase (full) or postgres (DB + S3 storage)
POSTGRES_URL	PostgreSQL connection string
SUPABASE_URL	Supabase project URL (required in supabase mode)
SUPABASE_PUBLISHABLE_KEY	Supabase anon/publishable key (supabase mode)
SUPABASE_SECRET_KEY	Supabase service role key (supabase mode)
STORAGE_ENDPOINT_URL	S3-compatible endpoint (required in postgres mode)
STORAGE_ACCESS_KEY_ID	S3 access key (postgres mode)
STORAGE_SECRET_ACCESS_KEY	S3 secret key (postgres mode)
STORAGE_BUCKET	Default S3 bucket name (postgres mode)
STORAGE_REGION	S3 region (default: us-east-1)
CATALOG_URI	Iceberg REST Catalog URI
ICEBERG_TOKEN	Bearer token for Iceberg catalog
ICEBERG_WAREHOUSE	Iceberg warehouse name
ICEBERG_NAMESPACE	Iceberg namespace (default: audit)
AWS_ACCESS_KEY_ID	S3-compatible access key
AWS_SECRET_ACCESS_KEY	S3-compatible secret key
S3_ENDPOINT	S3-compatible endpoint URL

---

Community

Contributions are subject to natuleadan review policies and terms.

Thanks to all contributors:

---

Star History

---

License

MIT © Leonardo Jara