What you can ask for
The Model Context Protocol (MCP) is how assistants like Claude and Cursor call tools on your computer. The Fileboy MCP server gives them the file operations the Node library already has, for one Fileboy app.
- "Find the PNGs over 2 MB uploaded this month." The assistant lists files with a type, size and date filter.
- "Upload ~/Desktop/hero.png into /Site and give me a 1200px wide WebP URL." It uploads the file, then builds the image URL.
- "Label the file we just uploaded as homepage_hero." Labels give a file a stable name, so the old file stops being served under it.
- "Move everything called invoice into /Accounting." It searches by name and moves the files in one call.
1. Get your keys
Open your app in the dashboard and copy the public and private key from its API keys page. Listing, changing and deleting files need the private key.
The private key has full access to the app, and Fileboy has no scoped or read-only keys yet. Try this on an app made for it, not your production app, and leave tool approval on so you see every delete.
2. Add the server to your assistant
It runs with npx, so you need Node.js 18 or newer and nothing else. Pick your assistant:
{
"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 mcp add fileboy \
--env FILEBOY_PUBLIC_KEY=your-public-key \
--env FILEBOY_PRIVATE_KEY=your-private-key \
-- npx -y @cd2/fileboy-mcp{
"mcpServers": {
"fileboy": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cd2/fileboy-mcp"],
"env": {
"FILEBOY_PUBLIC_KEY": "your-public-key",
"FILEBOY_PRIVATE_KEY": "your-private-key"
}
}
}
}{
"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 Desktop reads this from claude_desktop_config.json and Cursor from ~/.cursor/mcp.json. For VS Code, run MCP: Add Server and choose the NPM package, or use the config shown; the docs page also has the older .vscode/mcp.json format. Restart the app, then check that fileboy shows up in its list of tools.
3. Try it
Start with something that only reads: ask for your ten newest files. Each answer shows which tool the assistant used. Reading tools are marked read-only, and fileboy_delete_file is marked destructive, so assistants that honour those marks ask before deleting.
If a tool fails, the assistant gets Fileboy's own message and error code, for example that a folder does not exist, and can tell you what to change. If the server does not start at all, the assistant's MCP log names the missing environment variable.
What it cannot do
The server wraps what the Node library offers for files: list, search, details, upload, URLs, rename, move, label and delete, plus folders and saved transform presets. It does not create presets, manage webhooks or play video. For anything else, call the HTTP API from your own code.
Checked against the current libraries in November 2026. Found something that no longer works? Tell us.