Let Claude, Cursor, VS Code and other AI assistants that support the Model Context Protocol find, upload, transform and organise the files in your Fileboy app.
@cd2/fileboy-mcp is a Model Context Protocol server that runs on your computer, over stdio, and uses your app's API keys. It is a thin layer over the Node library: every tool is something that library already does. Once it is set up you can ask your assistant things like "find the images over 2 MB from this month", "upload this screenshot and give me a 600px wide WebP link" or "move last week's invoices into /Accounting".
It needs Node.js 18 or newer, which the assistant uses to run it with npx. There is nothing to install by hand.
You need your app's public and private key from its API keys page in the dashboard. Pick your assistant:
Claude Desktop. Open Settings, Developer, Edit Config, add this to claude_desktop_config.json and restart Claude.
1 2 3 4 5 6 7 8 9 10 11 12 13{ "mcpServers": { "fileboy": { "type": "stdio", "command": "npx", "args": ["-y", "@cd2/fileboy-mcp"], "env": { "FILEBOY_PUBLIC_KEY": "your-public-key", "FILEBOY_PRIVATE_KEY": "your-private-key" } } } }
Claude Code. Run this once. Add --scope user to have it in every project.
1claude mcp add fileboy --env FILEBOY_PUBLIC_KEY=your-public-key --env FILEBOY_PRIVATE_KEY=your-private-key -- npx -y @cd2/fileboy-mcp
Cursor. Add this to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one project.
1 2 3 4 5 6 7 8 9 10 11 12 13{ "mcpServers": { "fileboy": { "type": "stdio", "command": "npx", "args": ["-y", "@cd2/fileboy-mcp"], "env": { "FILEBOY_PUBLIC_KEY": "your-public-key", "FILEBOY_PRIVATE_KEY": "your-private-key" } } } }
VS Code. VS Code's docs now point new setups at its guided flow: run MCP: Add Server in the Command Palette, choose NPM Package, enter @cd2/fileboy-mcp and add the two environment variables. To write the file yourself, put this in your user MCP config (~/.copilot/mcp-config.json), or in .mcp.json at the workspace root if you have turned on chat.mcp.workspaceRootConfig.enabled.
1 2 3 4 5 6 7 8 9 10 11 12 13{ "mcpServers": { "fileboy": { "type": "stdio", "command": "npx", "args": ["-y", "@cd2/fileboy-mcp"], "env": { "FILEBOY_PUBLIC_KEY": "your-public-key", "FILEBOY_PRIVATE_KEY": "your-private-key" } } } }
The older .vscode/mcp.json (VS Code's Local harness, which its docs call deprecated, with removal planned for February 2027) still works. Its inputs section has VS Code ask for the private key when the server starts, so it stays out of the file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21{ "servers": { "fileboy": { "type": "stdio", "command": "npx", "args": ["-y", "@cd2/fileboy-mcp"], "env": { "FILEBOY_PUBLIC_KEY": "your-public-key", "FILEBOY_PRIVATE_KEY": "${input:fileboy-private-key}" } } }, "inputs": [ { "id": "fileboy-private-key", "type": "promptString", "description": "Fileboy private key", "password": true } ] }
Other assistants that run stdio MCP servers use the same command: npx -y @cd2/fileboy-mcp with the environment variables below.
| Variable | Required | What it is |
|---|---|---|
FILEBOY_PUBLIC_KEY | Yes | Your app's public key, from its API keys page. |
FILEBOY_PRIVATE_KEY | Yes | Your app's private key. Listing, changing and deleting files need it. It signs requests on your computer and is never put in a tool answer. |
FILEBOY_API_URL | No | Another Fileboy API to talk to. Only for developing Fileboy itself: it defaults to https://api.fileboy.io. |
If a required variable is missing the server stops when it starts and says which one, so the problem shows up in your assistant's MCP log instead of as a failing tool later.
| Tool | Kind | What it does |
|---|---|---|
fileboy_list_files | Read only | List or search files by name, type, label, folder, size, image size, date or metadata. Pages with a cursor. |
fileboy_get_file | Read only | One file's details, optionally its colour palette or EXIF (without GPS and serial numbers). |
fileboy_upload_file | Changes data | Upload from a path on your computer or from a URL, into a folder, with metadata. |
fileboy_image_url | Read only | Build an image URL: width, height, fit, format, quality, a saved preset or more transforms, optionally signed. |
fileboy_file_url | Read only | Build a file URL, optionally a download link or signed. |
fileboy_rename_file | Changes data | Rename a file. |
fileboy_move_files | Changes data | Move up to 100 files into a folder (by path or id) or to the root. |
fileboy_label_file | Changes data | Add or remove labels on a file. A label points at one file, so adding it moves it from any other. |
fileboy_delete_file | Destructive | Delete a file for good. Marked destructive, so assistants ask first. |
fileboy_list_folders | Read only | List folders and their paths, for moving or uploading into one. |
fileboy_list_transform_presets | Read only | List the app's saved transform presets, to use with fileboy_image_url. |
The reading tools are annotated read-only and delete is annotated destructive, so assistants that honour those hints ask before running it. Answers are compact JSON. When Fileboy refuses something the tool returns an error with Fileboy's own message and error code, so the assistant can explain it. Image URLs are built on your computer with the same builder as the Node library, so they use the image transforms and signed URLs you already know.
The private key has full access to the app. Whoever holds it can read, change and delete every file, and an assistant using this server can do anything its tools allow, including deleting files. Fileboy does not have scoped or read-only keys yet, so limit the risk yourself:
--scope user), and VS Code's older .vscode/mcp.json can prompt for it.The server never prints the keys: they are removed from every error message and never appear in a tool answer. The upload tool can send any file on your computer that the assistant names, and its instructions tell the assistant to upload only files you asked for and never keys, credentials or dotfiles. That is an instruction to the assistant, not a guard, and text in a web page or document the assistant reads can try to override it, so check the path in each upload before you approve it. A URL upload is fetched by Fileboy, not by your computer.
The package README has the development notes. For code instead of an assistant, use the libraries or the HTTP API, and see Use Fileboy from Claude or Cursor for a walk-through.