MCP server

The FileForge MCP server lets any Model Context Protocol–capable AI agent — Claude Desktop, Claude Code, Cursor, Windsurf, … — convert files without learning this REST API. The agent calls one tool with a file and a target format; the server handles upload, virus-scan, conversion, polling, and download for you.

It is a thin client of the Public API: same ff_live_… keys, same tiers, same scan/limits. It adds no new endpoints.

New to MCP? Start with the step-by-step MCP setup guide — it walks you through generating a key, installing in your client (Claude Code, Claude Desktop, Cursor, Windsurf), and running your first conversion. This page is the tool/config reference.

Install

Add it to your MCP client config and set your API key (create one):

{
  "mcpServers": {
    "fileforge": {
      "command": "npx",
      "args": ["-y", "@obrahaus/fileforge-mcp"],
      "env": { "FILEFORGE_API_KEY": "ff_live_…" }
    }
  }
}

• Claude Desktop / Cursor / Windsurf — add the block above to the app's MCP config (claude_desktop_config.json / the editor's MCP settings).
• Claude Code — claude mcp add fileforge -e FILEFORGE_API_KEY=ff_live_… -- npx -y @obrahaus/fileforge-mcp

The server speaks stdio and runs on any Node ≥ 20.18 — no native dependencies. Logs go to stderr; stdout carries only protocol traffic.

Developing or pointing at a non-production environment? You can also run it from a source build — see the setup guide.

Tools

convert_file

The one-call, do-everything tool. Give it a file and a target format; it uploads, converts, waits, and downloads the result.

• Input: source (exactly one of path — a local file, url, or base64 bytes; plus filename when needed), target_format, optional preset, options (see conversion options), preserve_metadata, output (path / overwrite / return_bytes), timeout_seconds.
• Output: on completion, the local output_path (when the input was a path) or a download_url; on a slow job that outlasts the wait, a non-fatal { status: "processing", conversion_id } you can resume with get_conversion_status — no re-upload.

list_formats

Discover what's possible and what options each target accepts (tier-filtered) — the agent's substitute for reading these docs. Input: optional input_path / source_format / target_format.

get_conversion_status

Check a previously-started conversion and optionally download its result (fresh presigned URLs are minted each call). Input: conversion_id, optional output.

convert_files

Convert many files in one bulk job (Forge Pro). Input: items[], optional output_dir, overwrite, timeout_seconds.

Example agent transcripts

• "Convert ~/Desktop/logo.png to a favicon with sizes 16, 32, 48." → the agent calls convert_file with target_format: "ico", options: { sizes: "16,32,48" } and writes ~/Desktop/logo.ico.
• "Make a web-sized WebP of photo.jpg at 1200px wide." → convert_file with target_format: "webp", options: { width: 1200, quality: 82 }.
• "Extract pages 1–3 of contract.pdf and password-protect it." (Pro) → convert_file target_format: "pdf", options: { page_range: "1-3", password: "…" }.

File handling

• Local path → local path (default, stdio): the result is written next to the input (or to output.path), and the path is returned.
• URL or base64 bytes in: the server fetches/decodes the input and returns a presigned download_url (or inlined base64 when small, via output.return_bytes).
• File bytes stream directly to/from FileForge storage — they never cross the MCP channel — so large files (up to your tier's 500 MB / 2 GB limit) work with flat memory.

Configuration

Env var	Default	Purpose
FILEFORGE_API_KEY	— (required)	Your ff_live_… key.
FILEFORGE_API_BASE_URL	https://fileforge-api.obrahaus.com/v1	Override to target a non-production FileForge environment (develop: https://fileforge-api.obrahaus-develop.aldrickb.xyz/v1).
FF_MCP_MAX_POLL_SECONDS	300	Hard ceiling on any tool's wait loop.
FF_MCP_MAX_INLINE_BYTES	5242880	Max size for base64-inlined results.
FF_MCP_OUTPUT_DIR	—	Default directory for outputs.
FF_MCP_LOG_LEVEL	info	debug / info / warn / error (stderr only).

Tiers & errors

The MCP shares the Public API's tier gating: Free is 5 conversions/day with no bulk; Forge Pro unlocks unlimited conversions, larger files, bulk, and Pro-only options (passwords, etc.). Tool errors map the API's error codes to actionable messages (e.g. an unsupported pair lists the valid targets; a Pro-only option explains the plan requirement).

Transport note: the GA server is stdio (local agent). A hosted HTTP transport for remote agents is on the roadmap.