MCP and command line

switchfile has two MCP servers. The hosted server at https://mcp.switchfile.io/mcp works in claude.ai and ChatGPT; you sign in with your switchfile account, no API key needed. The npm package switchfile-mcp runs on your computer for coding agents such as Claude Code or Cursor and converts local files.

Hosted server#

Address: https://mcp.switchfile.io/mcp. Sign-in uses OAuth with your switchfile account: the assistant opens a switchfile page where you sign in and allow access. The assistant can then convert files and read your conversions. Conversions count toward your daily limit and credits like API requests.

Claude (claude.ai and the desktop app): add a custom connector in the settings under Connectors, paste the address, then connect and sign in.

ChatGPT: add an app with the same address in the settings under Apps and connectors, then sign in. Custom apps need developer mode, which ChatGPT turns on in the advanced settings of that page.

You see every connected app under Connected apps and can disconnect it there. A new password disconnects every app; connect it again afterwards.

Tools of the hosted server#

The converting tools wait up to 25 seconds for the result. A longer conversion returns its ID, and the assistant asks get_conversion again later. With inline: true, results up to 64 KB come back as file content in the chat, at most 10 files and 256 KB together; larger results come only as links.

Each account can make 120 tool calls per minute. For create_upload from code execution in Claude, allow the host of the upload URL (api.switchfile.io) in Claude's network settings; otherwise the upload is blocked.

Local server (npm)#

The npm package switchfile-mcp is an MCP server and a command line tool. Agents in Claude Code, Codex, Cursor, VS Code and other MCP clients can convert files on your computer; the result is saved next to the input file. It needs Node.js 18 or newer and an API key.

Add it to your client#

Claude Code:

claude mcp add switchfile -e SWITCHFILE_API_KEY=your_key -- npx -y switchfile-mcp

Claude Code with the plugin, which also adds a skill for file conversion:

claude plugin marketplace add floraiNx/switchfile-plugins
claude plugin install switchfile@switchfile

Codex, in ~/.codex/config.toml. Codex stops tools after 60 seconds by default; tool_timeout_sec gives long conversions time to finish:

[mcp_servers.switchfile]
command = "npx"
args = ["-y", "switchfile-mcp"]
env_vars = ["SWITCHFILE_API_KEY"]
tool_timeout_sec = 900

Cursor, in ~/.cursor/mcp.json or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "switchfile": {
      "command": "npx",
      "args": ["-y", "switchfile-mcp"],
      "env": { "SWITCHFILE_API_KEY": "${env:SWITCHFILE_API_KEY}" }
    }
  }
}

Other clients start the server the same way: command npx, arguments -y switchfile-mcp, and the API key in the environment variable SWITCHFILE_API_KEY.

Tools of the local server#

Existing files are never replaced unless overwrite is true, and the input file is never replaced. Several results, such as one PNG per PDF page, are saved as name-1.png, name-2.png and so on.

Command line#

The same package has a switchfile command:

export SWITCHFILE_API_KEY=your_key
npx -y -p switchfile-mcp switchfile convert talk.mkv --to mp4
npx -y -p switchfile-mcp switchfile convert scan.pdf --to png --out pages/
npx -y -p switchfile-mcp switchfile convert photo.heic --to jpg -o quality=85
npx -y -p switchfile-mcp switchfile formats --from heic
npx -y -p switchfile-mcp switchfile account

Run switchfile --help for all commands. Add --json for output that scripts can read.