MCP 服务器

mcp-backend

MCP server providing backend access to PostgreSQL, Storage (Supabase/S3), Iceberg data lake, and SQL seeds. It offers 32 tools for database queries, storage operations, seed management, and more.

README

<h1 align="center">mcp-backend</h1> 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