MCP server for AI assistants

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.

What it does

@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.

Set it up

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.

1
claude 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.

Environment variables

VariableRequiredWhat it is
FILEBOY_PUBLIC_KEYYesYour app's public key, from its API keys page.
FILEBOY_PRIVATE_KEYYesYour 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_URLNoAnother 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.

Tools

ToolKindWhat it does
fileboy_list_filesRead onlyList or search files by name, type, label, folder, size, image size, date or metadata. Pages with a cursor.
fileboy_get_fileRead onlyOne file's details, optionally its colour palette or EXIF (without GPS and serial numbers).
fileboy_upload_fileChanges dataUpload from a path on your computer or from a URL, into a folder, with metadata.
fileboy_image_urlRead onlyBuild an image URL: width, height, fit, format, quality, a saved preset or more transforms, optionally signed.
fileboy_file_urlRead onlyBuild a file URL, optionally a download link or signed.
fileboy_rename_fileChanges dataRename a file.
fileboy_move_filesChanges dataMove up to 100 files into a folder (by path or id) or to the root.
fileboy_label_fileChanges dataAdd or remove labels on a file. A label points at one file, so adding it moves it from any other.
fileboy_delete_fileDestructiveDelete a file for good. Marked destructive, so assistants ask first.
fileboy_list_foldersRead onlyList folders and their paths, for moving or uploading into one.
fileboy_list_transform_presetsRead onlyList 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.

Security

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:

  • Use an app made for this (or a copy of the one you work in) rather than your production app, until you are used to it.
  • Keep the key out of files you commit. Claude Code can keep it in your user config (--scope user), and VS Code's older .vscode/mcp.json can prompt for it.
  • Leave tool approval on, so you see each delete or move before it runs, and read the file id it names.
  • Check "Last used" on the keys page, and regenerate the keys if they ever end up somewhere they should not be.

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.

More

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.