Supabase Storage Server

A Claude Code plugin that lets you create storage buckets and upload media (images, video, audio, PDFs, design assets) to Supabase — just by chatting with Claude. It fills the gap left by the official Supabase MCP, which has no Storage bucket API.

Storage-only and additive-only by design:

• 🚫 No delete anything. There is no tool to delete, remove, or empty a bucket or file.
• 🚫 No overwrite. Uploads and moves never replace an existing file — a name clash fails cleanly.
• 🚫 No database access. The plugin exposes storage tools only; it cannot read or change your data.

Were you handed this folder to use, not to set up? Open START-HERE.md — a 3-minute, plain-language guide. The rest of this README is for whoever installs and configures it.

---

Part 1 — Setup (for whoever installs it)

What you need

• Node.js 18 or newer (node --version).
• Access to your Supabase project in the Supabase dashboard.

Step 1 — Get your two credentials from Supabase

In the Supabase dashboard, open the project, then:

1. Project URL — Project Settings → Data API → Project URL (looks like https://abcdefghijklmno.supabase.co).
2. Service role key — Project Settings → API Keys → reveal the service_role key.

⚠️ The service role key is sensitive — treat it like a password. It can access the whole project, so never commit it, paste it in chat, or share it. This plugin only ever uses it for Storage operations and exposes no database tools, but the key itself is still powerful. Keep it in the .env file (which is gitignored) and nowhere else.

Step 2 — Configure the plugin

1. Copy the template to a real env file, in the plugin folder:

   cp .env.example .env
   

2. Open .env and paste your two values:

   SUPABASE_URL=https://<your-project-ref>.supabase.co
   SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
   

Step 3 — Install and build

The plugin ships with a prebuilt dist/, so if you just cloned it you can usually skip straight to installing it in Claude. If you edited the source (or want to be sure), run:

npm install     # installs dependencies and builds dist/ automatically
npm test        # optional: runs the guardrail tests (should print "pass 10")

Step 4 — Install the plugin in Claude Code

Add this folder as a plugin (via your Claude Code plugin marketplace/config). The plugin's .claude-plugin/plugin.json registers a local stdio MCP server that runs dist/index.js. Once installed, Claude will have eight supabase-storage tools and the /upload-media guide available.

To verify quickly from a terminal, you can start the server directly — it should print supabase-storage MCP server ready:

npm start

The eight tools

Tool	What it does
list_buckets	List buckets with their public/private, size limit, and allowed types
create_bucket	Create a bucket (naming convention enforced; defaults to private, 50MB, common media)
upload_file	Upload a local file (validates type + size first; never overwrites)
list_files	List files in a bucket (optionally in a folder), with sizes and dates
get_signed_url	Make a temporary shareable link (default 7 days) — works for private buckets
get_public_url	Get the permanent public link — for public buckets
move_file	Rename or move a file — within a bucket or into another bucket (never overwrites)
copy_file	Copy a file — within a bucket or into another bucket — keeping the original (never overwrites)

Bucket naming convention

Enforced in code. A bucket name must start with an allowed category prefix, then lowercase words joined by dashes:

^(marketing|brand|campaigns|media|assets)(-[a-z0-9]+)+$

Examples: marketing-q3-launch, brand-logos, campaigns-spring-2026, media-product-shots, assets-social-templates.

To add or change the allowed prefixes, edit ALLOWED_BUCKET_PREFIXES in src/config.ts and run npm run build.

---

Part 2 — How to use it (for the marketing team)

You don't need to know any of the technical stuff. Just talk to Claude. Try the /upload-media command, or say things like:

• "What storage buckets do we have?" → Claude lists them.
• "Make a new bucket for the Q3 launch." → Claude creates marketing-q3-launch (it'll ask if it should be private or public).
• "Upload C:\Users\me\Pictures\hero.png to the marketing-q3-launch bucket." → Claude uploads it and tells you where it landed.
• "Give me a shareable link for hero.png." → Claude makes a link (a temporary one for private buckets, valid 7 days by default; a permanent one for public buckets).
• "Rename hero.png to hero-final.png." → Claude moves it.

Good to know:

• Nothing you do here can delete or overwrite a file. If a name is already taken, Claude will ask you to pick a different one. Explore freely.
• Private vs public: private files are shared with a temporary link; public files (like logos) get a permanent web link. When in doubt, private is the safe default.
• If something doesn't work, Claude will explain it in plain language — e.g. "that file type isn't allowed here" or "that bucket doesn't exist yet." If it mentions credentials or the network, that's a setup issue — tell whoever installed the plugin; it's not something you did wrong.

---

Part 3 — Quick test checklist (for the installer, after setup)

Run through this once with Claude to confirm everything works end to end:

1. Create a bucket — ask Claude to create media-test-bucket (private). ✅ It's created.
2. Upload an image — ask Claude to upload a small image to it. ✅ It returns the stored path and offers a signed link.
3. List files — ask Claude to list files in media-test-bucket. ✅ Your image appears with its size and date.
4. Signed URL — ask for a shareable link to the image. ✅ You get a URL; opening it shows the image.
5. Duplicate upload fails — upload the same file to the same path again. ✅ It fails with "that name is already taken — choose a different name" (nothing is overwritten).
6. Bad bucket name fails — ask Claude to create a bucket called TestBucket or random-name. ✅ It's refused with an explanation of the naming rule.

If all six behave as described, the plugin is working.

---

How it's built

• TypeScript stdio MCP server using @modelcontextprotocol/sdk and @supabase/supabase-js.
• Source in src/ (one file per tool under src/tools/), compiled to dist/.
• Guardrails live in code: naming regex and defaults in src/config.ts; client-side validation in src/validation.ts; friendly error mapping in src/errors.ts.
• npm test runs guardrail tests, including a structural check that no destructive Storage call (.remove, deleteBucket, emptyBucket) and no upsert: true exists anywhere in the build.

This is an interim, disposable tool and may be replaced by a more complete solution later.