Filestack Plugin for Claude Code & Cursor

Official Filestack plugin for Claude Code and Cursor — 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 your coding agent through 19 MCP tools, 5 context-aware skills, and a natural language slash command. Upload files, build transformation pipelines, run AI/ML analysis (tagging, OCR, captioning, moderation), convert documents and videos, bundle ZIPs, capture web screenshots, run workflows, generate signed security policies, verify webhook signatures, set up integrations, and debug API errors — all through conversation without leaving the terminal.

Table of Contents

• Supported Platforms

• Installation

• Configuration

• MCP Tools

  • File Operations

  • Transformations

  • Security

• Skills

  • filestack-sdk-integration

  • filestack-error-diagnosis

  • filestack-webhook-setup

• Slash Command

• Examples

• Available Transformations

• Troubleshooting

• Documentation

• License

Related MCP server: Multimodal MCP Server

Supported Platforms

This plugin works with both Claude Code and Cursor. Install it from either marketplace and the correct configuration is detected automatically.

Installation

From marketplace (recommended):

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

The plugin works immediately with a built-in demo API key. For full access to your own Filestack account, set your API key (see Configuration).

Don't have a Filestack account yet? Sign up free at https://dev.filestack.com/signup/free/

Configuration

The plugin runs a local MCP server and works out of the box with a demo API key (APQLlwqrRScGxhw78gs9Wz). To use your own Filestack account, set your API key as an environment variable before starting your editor:

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

You can find your API key and app secret in the Filestack Developer Portal.

The MCP server runs locally via Node.js. Policy signing happens on your machine — your app secret never leaves your environment.

MCP Tools

The plugin exposes 19 tools across 7 categories:

File Operations

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:

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:

filestack_delete

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

"Delete file handle abc123XYZ"

Parameters:

filestack_store_url

Ingest a remote URL into Filestack storage. The file is fetched server-side — no download needed on your end.

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

Parameters:

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

Transformations

filestack_transform_url

Build a Filestack CDN transformation URL from structured parameters. This is a pure URL construction — no API call, no API key required.

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

Parameters:

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:

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?"

Security

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:

filestack_sign_policy

Sign a base64-encoded policy with HMAC-SHA256 using your app secret. The signing happens locally — your secret never leaves your machine.

"Sign this policy: eyJjYWxsIjpbInJlYWQiXX0"

Parameters:

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:

Returns: { policy, signature, signedUrl }

Requires: Both FILESTACK_API_KEY and FILESTACK_APP_SECRET environment variables

Intelligence

filestack_analyze

Run a Filestack AI/ML task on a file (or text). One tool, 8 tasks:

"Is this image SFW?"
"What's in this image?"
"Extract text from this receipt"

Parameters:

Security note: when app security is enabled, the signing policy must include convert in call.

Video intelligence (video_sfw, video_tagging) is not a direct task — use filestack_run_workflow with a workflow that includes the video intelligence step.

Document & Video

filestack_convert_document

Convert documents between formats (DOC/DOCX/ODT/PPT/PPTX/ODP/XLS/XLSX/ODS/HTML/TXT/PDF and image formats JPG/PJPG/PNG/WebP/SVG).

"Convert handle abc123 to PDF"
"Extract page 3 of this PDF as a 300dpi PNG"

Parameters:

filestack_convert_video

Submit a Telestream-backed video transcode job. Async — returns { uuid, status_url, timestamp }. Use filestack_video_status to poll, or configure a webhook subscribed to fp.video_converse.

"Transcode handle abc123 to HLS for streaming"
"Convert this video to 720p H.264 MP4"

Parameters:

filestack_video_status

Poll a previously submitted video conversion job.

Parameters:

Archive & Capture

filestack_zip_files

Bundle up to 100 file handles into a single ZIP CDN URL. Pure URL construction — no API call until the URL is fetched.

"Bundle handles abc123, def456, ghi789 as a ZIP"

Parameters:

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

filestack_screenshot_url

Capture a screenshot of a target web URL. Pure URL construction.

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

Parameters:

Workflows & Webhooks

filestack_run_workflow

Invoke a saved Filestack Workflow (designed in dev.filestack.com → Workflows). Workflows handle multi-step async pipelines, virus detection, video intelligence (video_sfw, video_tagging), and any branching logic.

"Run workflow 67d273c3-... on handle abc123XYZ"

Parameters:

filestack_verify_webhook_signature

Verify a received Filestack webhook's HMAC-SHA256 signature locally — no network call. Use in your webhook receiver to authenticate requests.

"Verify this incoming webhook is genuinely from Filestack"

Parameters:

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

filestack_sign_webhook_payload

Generate FS-Signature and FS-Timestamp headers for a given body + secret. Useful for testing your own webhook receiver locally without triggering a real upload event.

Parameters:

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

Skills

Skills activate automatically based on conversation context. They provide Claude with domain-specific knowledge about Filestack patterns, best practices, and debugging techniques.

filestack-sdk-integration

Activates when: You import Filestack SDKs (filestack-js, from filestack import), use SDK methods (client.picker(, client.upload(), reference picker config options (fromSources, storeTo, acceptedFileTypes), or 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: You encounter Filestack API errors — HTTP 401/403/404/429, domain tokens (filestackapi.com, filestackcontent.com), error response shapes ({"result": "error"}, {"error": ..., "result": null}), or 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: You work with Filestack webhook headers (FS-Signature, FS-Timestamp), event types (fp.upload, fp.converse, fp.delete, fp.video_converse, fp.scan), or ask about Filestack event notifications.

Provides:

• Complete webhook event type reference with trigger conditions

• Webhook registration API with curl examples

• Webhook payload shape documentation

• HMAC-SHA256 signature verification code in three languages:

  • Node.js/TypeScript — Express handler with raw body capture

  • Python — Flask handler with hmac.compare_digest

  • Go — Standard library verification function

• 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

/filestack-transform

Convert plain-English descriptions into Filestack CDN transformation URLs.

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

Examples:

/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

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

Examples

Upload a file and get a CDN URL

"Upload ./hero-banner.jpg to Filestack"

Claude calls filestack_upload and returns:

{
  "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 400x400, 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 in the canonical Filestack path-based form (chainable with transforms):

https://cdn.filestackcontent.com/security=policy:eyJ...,signature:a1b2c3.../XYZ123

Debug a 403 error

"I'm getting {"result": "error", "error": {"code": 403, "msg": "Policy required"}} from the v1 API"

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 — no download-then-reupload needed.

Available Transformations

The following transformations can be used with filestack_transform_url, filestack_transform_apply, and /filestack-transform:

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

Troubleshooting

Documentation

• Filestack Documentation

• Processing API Reference

• Security Policies Guide

• Webhooks Guide

• JavaScript SDK Reference

• Filestack Developer Portal

License

MIT