Claude Code Plugin

Filestack Plugin for Claude Code

Official Claude Code plugin for Filestack – the file handling platform-as-a-service for uploads, cloud source ingestion, on-the-fly image/video/document processing, CDN delivery, and policy-based security.

This plugin brings the full Filestack platform into Claude Code through 10 MCP tools, 3 context-aware skills, and a natural language slash command. Upload files, build transformation pipelines, generate signed security policies, set up webhooks, and debug API errors – all through conversation, right in the terminal.

View on GitHub

Installation

Two ways to install the plugin into Claude Code.

From Marketplace (Recommended)

Claude Code

/plugin marketplace add https://github.com/filestack/filestack-claude-plugin.git
/plugin install filestack-claude-plugin@filestack-plugin

Manual

bash

git clone https://github.com/filestack/filestack-claude-plugin.git
cd filestack-claude-plugin/mcp && npm install && npm run build

Configuration

Set these environment variables before starting Claude Code.

bash

export FILESTACK_API_KEY=your_api_key 
export FILESTACK_APP_SECRET=your_app_secret  # only needed for security tools

Find your API key and app secret in the Filestack Developer Portal.

Variable	Required	Used by
FILESTACK_API_KEY	`Yes`	All file operation and transformation tools
FILESTACK_APP_SECRET	`Security only`	`filestack_sign_policy`,`filestack_generate_signed_url`

MCP Tools – File Operations

Upload, retrieve, delete, and ingest remote files.

`filestack_upload`

Upload a local file or remote URL to Filestack and get a CDN-ready file handle.

Upload ./product-photo.jpg to Filestack

Upload https://example.com/image.png to Filestack

Parameters

Parameter	Type	Required	Description
filePath	string	Yes	Local file path or remote URL
storeOptions	object	No	Storage options: `location`, `path`, `container`, `access`

Returns: { handle, url, filename, size, type }

`filestack_retrieve`

Get metadata for any file handle – size, MIME type, dimensions, upload date, etc.

What's the metadata for file handle abc123XYZ?

Parameters

Parameter	Type	Required	Description
handle	string	Yes	Filestack file handle

`filestack_delete`

Delete a stored file. If your app has security enabled, include a policy and signature.

Delete file handle abc123XYZ

Parameters

Parameter	Type	Required	Description
handle	string	Yes	Filestack file handle
policy	string	No	Base64-encoded security policy (if security is enabled)
signature	string	No	HMAC-SHA256 hex signature (if security is enabled)

`filestack_store_url`

Ingest a remote URL into Filestack storage. The file is fetched server-side, so it’s ready in storage immediately.

Store https://example.com/document.pdf in Filestack

Parameters

Parameter	Type	Required	Description
sourceUrl	string	Yes	Remote URL to store
storeOptions	object	No	Storage options: `location`, `path`, `container`, `access`

Returns: { handle, url, filename, size, type }

MCP Tools – Transformations

Build transformation URLs or apply and persist image/video/document processing pipelines.

`filestack_transform_url`

Build a Filestack CDN transformation URL from structured parameters. Pure URL construction – no API call, no API key required.

Build a URL that resizes abc123XYZ to 800x600 and converts to webp

Parameters

Parameter	Type	Required	Description
handleOrUrl	string	Yes	File handle or full CDN URL
transforms	array	Yes	Array of `{ operation, params }` objects

Returns: The constructed CDN URL, e.g.:

https://cdn.filestackcontent.com/ resize=width:800,height:600/output=format:webp abc123XYZ

`filestack_transform_apply`

Apply transformations to a file and persist the result as a new file handle. Unlike transform_url, this executes the transformation and stores the output.

Resize abc123XYZ to 400x400, enhance it, and save the result

Parameters

Parameter	Type	Required	Description
handleOrUrl	string	Yes	File handle or full CDN URL
transforms	array	Yes	Array of `{ operation, params }` objects
storeOptions	object	No	Where to store the result

Returns: { handle, url } for the new transformed file

`filestack_list_transforms`

List all available transformation operations with their parameters, types, and valid values.

What transformations does Filestack support?

MCP Tools – Security

Generate and sign HMAC-SHA256 policies. Requires FILESTACK_APP_SECRET.

`filestack_generate_policy`

Generate a base64-encoded security policy with scoped permissions. Policies control what operations are allowed and for how long.

Generate a read-only policy that expires in 1 hour

Parameters

Parameter	Type	Required	Description
call	string or array	Yes	Permission scope(s): `read`, `stat`, `write`, `writeUrl`, `store`, `convert`, `remove`, `revoke`, `pick`, `exif`, `runWorkflow`
expiry	number	Yes	Unix timestamp (seconds) when the policy expires
handle	string	No	Restrict to a specific file handle
path	string	No	Restrict to a path prefix
container	string	No	Restrict to a storage container
minSize	number	No	Minimum file size in bytes
maxSize	number	No	Maximum file size in bytes

`filestack_sign_policy`

Sign a base64-encoded policy with HMAC-SHA256 using your app secret. The signing happens locally. Your secret stays on your machine.

Sign this policy: eyJjYWxsIjpbInJlYWQiXX0

Parameters

Parameter	Type	Required	Description
policy	string	Yes	Base64-encoded policy from `filestack_generate_policy`

Requires: FILESTACK_APP_SECRET environment variable

`filestack_generate_signed_url`

One-step convenience tool: generates a policy, signs it, and returns a fully signed CDN URL ready to use.

Give me a signed URL for handle XYZ123 with read access, valid for 2 hours

Parameters

Parameter	Type	Required	Description
handle	string	Yes	Filestack file handle
call	string or array	Yes	Permission scope(s)
expiry	number	Yes	Unix timestamp (seconds)
container	string	No	Restrict to container
path	string	No	Restrict to path prefix
minSize	number	No	Minimum file size in bytes
maxSize	number	No	Maximum file size in bytes

Returns: { policy, signature, signedUrl }

Requires: Both FILESTACK_API_KEY and FILESTACK_APP_SECRET

Skills

Skills activate automatically based on conversation context – no manual invocation needed.

How skills work: Claude detects relevant patterns in your code, imports, error messages, or questions and automatically loads domain-specific knowledge about Filestack patterns, best practices, and debugging techniques.

filestack-sdk-integration

Activates when

filestack-js from filestack import client.picker( client.upload() fromSources storeTo acceptedFileTypes

Also activates when you ask how to add file upload to your app.

Provides

SDK initialization for JavaScript/TypeScript and Python
CDN loader setup (no bundler required)
Picker widget configuration – accepted file types, cloud sources, storage options, size limits
Upload response shape and TypeScript interfaces
Framework-specific patterns for React and Next.js
Common mistakes: wrong API key scope, missing CORS whitelist, transform chain ordering, unawaited upload promises

filestack-error-diagnosis

Activates when

filestackapi.com filestackcontent.com HTTP 401 HTTP 403 HTTP 404 HTTP 429 {"result": "error"} result: null

Also activates when you paste a Filestack error message.

Provides

HTTP error code reference with likely causes and fixes
Security policy error breakdown – expired policy, wrong signature, insufficient scope, CORS origin
Transformation error table – unsupported format, size limit, timeout, invalid parameter
Step-by-step diagnosis checklist: API key validation, policy expiry check, handle existence, CORS whitelist, transform parameter verification, rate limit detection

filestack-webhook-setup

Activates when

FS-Signature FS-Timestamp fp.upload fp.converse fp.delete fp.video_converse fp.scan filestack_webhook

Also activates when you paste a Filestack error message.

Provides

Complete webhook event type reference with trigger conditions
Webhook registration API with curl examples
Webhook payload shape documentation
HMAC-SHA256 signature verification in three languages: Node.js/TypeScript (Express), Python (Flask), Go (stdlib)
Critical production patterns: return 200 before processing, idempotency via event ID, raw body preservation for signature verification
Retry behavior: 5 retries with exponential backoff (10s, 60s, 5min, 15min, 1hr)

Slash Command

Convert plain-English descriptions into Filestack CDN transformation URLs.

/filestack-transform <handle-or-url> <description>

Accepts bare handles or full CDN URLs. If called with no arguments, shows usage and examples.

Examples

Claude Code

/filestack-transform abc123XYZ resize to 800x600 and convert to webp
-> https://cdn.filestackcontent.com/resize=width:800,height:600/output=format:webp/abc123XYZ

 /filestack-transform abc123XYZ detect face, enhance, and convert to jpg at 85 quality
-> https://cdn.filestackcontent.com/crop_faces=faces:1/enhance/output=format:jpg,quality:85/abc123XYZ

 /filestack-transform https://cdn.filestackcontent.com/abc123XYZ rotate 90 and monochrome
-> https://cdn.filestackcontent.com/rotate=deg:90/monochrome/abc123XYZ

Examples

Real-world conversation examples and what Claude returns.

Upload a file and get a CDN URL

“Upload ./hero-banner.jpg to Filestack”

Claude calls filestack_upload and returns:

json

{
  "handle": "abc123XYZ",
  "url": "https://cdn.filestackcontent.com/abc123XYZ",
  "filename": "hero-banner.jpg",
  "size": 245760,
  "type": "image/jpeg"
}

Build an image processing pipeline

“Take handle abc123XYZ, crop to the detected face, resize to 400×400, enhance colors, and output as webp”

Claude calls filestack_transform_url and returns:

https://cdn.filestackcontent.com/ crop_faces=faces:1/resize=width:400,height:400,fit:crop/enhance/output=format:webp abc123XYZ

Generate a time-limited signed URL

“I need a signed URL for handle XYZ123 that allows read access for 2 hours”

Claude calls filestack_generate_signed_url and returns a policy, signature, and ready-to-use URL:

https://cdn.filestackcontent.com/XYZ123?apikey=YOUR_KEY&policy=eyJ...&signature=a1b2c3...

Debug a 403 error

“I’m getting {"result": "error", "error": {"code": 403, "msg": "Policy required"}} from the CDN”

Claude activates the filestack-error-diagnosis skill and walks through: Is security enabled on your app? Is the policy expired? Does the policy include read scope? Is your CORS origin whitelisted?

Add file upload to a React app

“Add image upload to my React app with Google Drive and Dropbox support”

Claude activates filestack-sdk-integration and generates a complete React component with the Filestack picker configured for the specified cloud sources, file type restrictions, and upload callbacks.

Set up webhook verification

“I need a Node.js endpoint to receive Filestack upload events with signature verification”

Claude activates filestack-webhook-setup and provides a production-ready Express handler with HMAC-SHA256 verification, raw body capture, immediate acknowledgment, and async processing.

Ingest files from external URLs

“Store these S3 URLs in Filestack so I can use the transformation CDN”

Claude calls filestack_store_url for each URL, returning handles that work with the full transformation and delivery pipeline – directly, with a single API call.

Available Transformations

Use with filestack_transform_url, filestack_transform_apply, and /filestack-transform.

Order matters: Transforms are chained left-to-right in the CDN URL. Put processing operations (resize, crop, enhance) before format conversion (output).

Transform	Description	Key Parameters
resize	Resize an image	`width`, `height`, `fit` (clip/crop/scale/max), `align`
crop	Crop to specific dimensions	`dim` as [x, y, width, height]
crop_faces	Detect faces and crop to them	`faces` (count), `buffer` (padding %)
rotate	Rotate an image	`deg` (0–359), `background` (hex color)
flip	Flip vertically	–
flop	Flip horizontally	–
enhance	Auto-enhance image quality	–
monochrome	Convert to grayscale	–
sepia	Apply sepia tone	`tone` (0–100)
blur	Blur image	`amount` (1–20)
sharpen	Sharpen image	`amount` (1–20)
compress	Compress image	`metadata` (preserve metadata)
watermark	Add watermark overlay	`file` (watermark handle), `size` (%), `position`
output	Convert format	`format` (jpg/png/webp/gif/pdf/svg), `quality` (1–100)

Remote MCP (Optional)

Run the MCP server remotely instead of locally.

Replace .mcp.json with:

.mcp.json

{
  "filestack": {
    "type": "http",
    "url": "https://mcp.filestack.com/mcp",
    "headers": {
      "Authorization": "Bearer ${FILESTACK_API_KEY}"
    }
  }
}

Tip: The remote endpoint stays up-to-date with the latest Filestack API automatically – no local rebuilds required.

Local vs Remote

	Local MCP	Remote MCP
Setup	Clone + npm build	.mcp.json only
Updates	Manual git pull + rebuild	Automatic
Works offline	Yes	No
Auth	Environment variables	Bearer token header

Troubleshooting

Common problems and their solutions.

Problem	Solution
Tools return “API key not configured”	Set `FILESTACK_API_KEY` and restart Claude Code
Security tools return “App secret not configured”	Set `FILESTACK_APP_SECRET` and restart Claude Code
Skills not appearing after install	Restart Claude Code – skills load at session start
`filestack_upload` fails for local files	Ensure the file path is absolute or relative to the working directory
`filestack_transform_apply` returns 403	Your API key may not have processing permissions – check the Filestack Developer Portal
Signed URLs return 403	Confirm the policy is still valid and includes the correct `call` scope for the operation