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

The plugin exposes 19 tools across 7 different categories.

Category	Tools
File operations	`filestack_upload`, `filestack_retrieve, filestack_delete, filestack_store_url`
Transformations	`filestack_transform_url`, `filestack_transform_apply, filestack_list_transforms`
Security	`filestack_generate_policy, filestack_sign_policy, filestack_generate_signed_url`
Intelligence (AI/ML)	`filestack_analyze`
Document and Video	`filestack_convert_document, filestack_convert_video, filestack_video_status`
Archive and Capture	`filestack_zip_files, filestack_screenshot_url`
Workflow and Webhooks	`filestack_run_workflow, filestack_verify_webhook_signature, filestack_sign_weebhook_payload`

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

MCP Tools – Intelligence

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

`filestack_analyze`

One unified entry point for eight different tasks. Backed by Rekognition, Vision, and Comprehend, this tool returns task-specific JSON files.

Accepts the following tasks: tags, sfw, caption, ocr, copyright, image_sentiment, doc_detection, text_sentiment.

Is this image SFW?
What is in this image?
Extract text from this receipt

Run any of the following Filestack AI/ML tasks on a file or text.

Task	Input	Result	Description
tags	image handle	`{ tags: { auto: { keyword: confidence } } }`	Use for auto-tagging and search indexing.
sfw	image handle	`{ sfw: boolean }`	Use for content moderation.
caption	image handle	`{ caption: "..." }`	Use for Alt-text and accessibility.
ocr	image or PDF handle	`{ text, blocks, confidence }`	Use for receipts, invoices, and signage.
copyright	image handle	`{ copyright, matches }`	Use for stock photo or IP enforcement.
image_sentiment	image handle	`{ sentiment, confidence }`	Use for emotion detection in faces.
doc_detection	photo of document	`{ detected, corners? }`	Use for mobile scanner UX.
text_sentiment	text string	`{ sentiment, confidence }`	Use for comment or review analysis.

Parameters

Parameter	Type	Required	Description
task	enum	Yes	One of the tasks listed above.
handleOrText	string	Yes	File handle (for file tasks) or text (for `text_sentiment`).
options	object	No	`{ coords, preprocess }` for `doc_detection`; `{ language }` for `text_sentiment`.

Note: When the app security is enabled, the signing policy must include convert in call.

Note: Video intelligence (video_sfw and video_tagging) is not a direct task. Use the filestack_run_workflow with a workflow that includes the video intelligence app.

MCP Tools – Document and Video

Convert videos or take screenshots for any URL.

`filestack_convert_document`

Convert between the following file and image formats.

File: DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, XLSX, ODS, HTML, TXT, PDF.

Image: JPG, PJPG, PNG, WebP, SVG.

Convert handle abc123 to PDF

Extract page 3 of this PDF as a 300dpi PNG

Parameters

Parameter	Type	Required	Description
handleOrUrl	string	Yes	Source handle or external URL.
format	enum	Yes	Target format (see list above).
options	object	No	`{ page, density, quality, pageformat, pageorientation, secure }`

`filestack_convert_video`

This option submits a Telestream transcode job. Accepts the following presets: h264, hls, dash, mp3, mp4, m4a, webm, etc., plus width, height, fps, bitrates, clip-offsets, and watermarks.

Transcode handle abc123 to HLS for streaming

Convert this video to 720p H.264 MP4

Parameters

Parameter	Type	Required	Description
handleOrUrl	string	Yes	Source handle or URL.
preset	string	Yes	`h264`, `hls`, `dash`, `mp3`, `mp4`, `m4a`, `webm`, etc.
options	object	No	`{ width, height, fps, video_bitrate, audio_bitrate, force, clip_offset, clip_lenght, watermark_url, email, ... }`

Returns:

{ uuid, status_url, timestamp }

`filestack_video_status`

Poll a previously submitted video conversion job.

Parameters

Parameter	Type	Required	Description
uuid	string	Yes	UUID returned by `filestack_convert_video`

MCP Tools – Archive and Capture

Zip files or capture screenshots for any URL.

`filestack_zip_files`

Bundle up to a hundred handles into a single ZIP CDN URL. With pure URL construction, no API call is needed until the URL is fetched.

Bundle handles abc123, def456, ghi789 as a ZIP

Parameters

Parameter	Type	Required	Description
handles	array of string	Yes	Filestack file handles (max 100)

Returns:

{ url: "https://cdn.filestackcontent.com/<APIKEY>/zip/[h1,h2,h3]" }

`filestack_screenshot_url`

Capture a screenshot of any web URL. Use it in desktop or mobile applications, and apply any of the following effects: viewport sizing, capture delay, or device profiles.

Screenshot https://example.com on a mobile viewport

Parameters

Parameter	Type	Required	Description
targetUrl	string	Yes	Full http(s) URL to capture
options	object	No	`{ agent: desktop/mobile, mode: all/window, width, height, delay, orientation, device }`

MCP Tools – Workflows and Webhooks

Invoke workflows and webhooks.

`filestack_run_workflow`

Invoke saved workflows from your Filestack Dev Portal account using a UUID. Covers the workflow-only capabilities: virus detection, video intelligence, phishing detection, and multi-step automated pipelines.

Run workflow 67d273c3-... on handle abc123XYZ

Parameters

Parameter	Type	Required	Description
handleOrUrl	string	Yes	File handle or external
workflowId	string (UUID)	Yes	Workflow UUID from the Developer Portal
options	object	No	Use `{ policy, signature }` for security-enabled apps. Policy must include `convert` and `runWorkflow` calls.

`filestack_verify_webhook_signature`

Drop this tool into a receiver to authenticate any incoming Filestack webhooks. This option performs a constant-time HMAC-SHA256 verification FS-Signature. Use in your webhook receiver to authenticate requests.

Verify this incoming webhook is genuinely from Filestack

Parameters

Parameter	Type	Required	Description
rawBody	string	Yes	A raw request body (exact bytes, capture before JSON parsing)
fsSignature	string	Yes	The `FS-Signature` header value
fsTimestamp	string	Yes	The `FS-Timestamp` header value
webhookSecret	string	Yes	Per-webhook secret from the Developer Portal

Returns:

{ valid: boolean, expected: string }(constant-time compare; expected for debugging only)

`filestack_sign_webhook_payload`

Generate FS-Signature and FS-Timestamp headers for any given body. This is great for testing a webhook receiver locally without triggering an upload event.

Parameters

Parameter	Type	Required	Description
body	string	Yes	Raw JSON body to sign
webhookSecret	string	Yes	Per-webhook secret
timestamp	number	No	Optional Unix timestamp. The default is “now”.

Returns:

{ "FS-Signature": <hex>, "FS-Timestamp": <str>, signPayload: "{ts}.{body}" }

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)

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