FileForge

Appearance

MCP setup guide ​

A start-to-finish walkthrough: generate an API key, install the FileForge MCP server in your AI client (Claude Code, Claude Desktop, Cursor, Windsurf, …), and run your first conversion. For the full tool/option/config reference, see the MCP server reference.

What you'll need

  • A FileForge account on Forge Pro (the API is a Pro feature).
  • Node.js ≥ 20.18 on the machine running your AI client (node -v). The server is launched with npx/node.
  • An MCP-capable client (Claude Code, Claude Desktop, Cursor, Windsurf, or any other MCP host).

Step 1 — Generate an API key ​

The MCP server authenticates with a normal FileForge API key (ff_live_…).

  1. Sign in at https://fileforge.obrahaus.com on a Forge Pro account (need Pro? upgrade here).
  2. Go to Settings → API Keys → New key.
  3. Give it a name (e.g. "Claude MCP") and select these scopes:
    • ✅ convert:write — create conversions
    • ✅ files:write — upload + finalize the input file
    • ✅ files:read (optional) — used by some flows
  4. Copy the key from the reveal dialog — it's shown only once. If you lose it, rotate the key (revoke + re-issue).

Scopes matter

The MCP's convert_file flow uploads your file (files:write) and creates the conversion (convert:write), so the key needs both. The app's default new-key scopes are convert:write + files:read — that's missing files:write, so an upload would fail with 403 forbidden. Make sure files:write is ticked.

See Authentication for the full key/scope reference.

Step 2 — Decide how the server runs ​

Every client config below needs a command + args. Pick one:

text
command: npx
args:    ["-y", "@obrahaus/fileforge-mcp"]
text
# one-time build in a checkout of the FileForge repo:
pnpm install
pnpm --filter @obrahaus/fileforge-mcp build

# then use the absolute path to the built entrypoint:
command: node
args:    ["/absolute/path/to/fileforge/apps/mcp/dist/index.js"]

The per-client configs below use the npm form. If you're running from source (building it yourself), substitute "command": "node", "args": ["/absolute/path/to/fileforge/apps/mcp/dist/index.js"] for the npx command + args (and for Claude Code, claude mcp add fileforge -e FILEFORGE_API_KEY=… -- node /absolute/path/to/fileforge/apps/mcp/dist/index.js), and set FILEFORGE_API_BASE_URL to target a non-production FileForge environment, e.g. develop (see Configuration).

Step 3 — Install in your client ​

Claude Code ​

Add it with one command (replace the key):

bash
claude mcp add fileforge -e FILEFORGE_API_KEY=ff_live_YOUR_KEY -- npx -y @obrahaus/fileforge-mcp
  • -e sets an env var; the -- separates Claude's flags from the server command.
  • Default scope is local (just you, this project). Use --scope user to make it available in all your projects, or --scope project to share it with a repo via a checked-in .mcp.json.

For a team-shared, project-scoped setup, commit a .mcp.json at the repo root and have each member export the key in their shell:

json
{
  "mcpServers": {
    "fileforge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@obrahaus/fileforge-mcp"],
      "env": { "FILEFORGE_API_KEY": "${FILEFORGE_API_KEY}" }
    }
  }
}
bash
export FILEFORGE_API_KEY=ff_live_YOUR_KEY   # in your shell profile

Claude Code expands ${FILEFORGE_API_KEY} from your environment and asks you to approve a project-scoped server the first time you open the session.

Verify: claude mcp list (look for fileforge ✓ Connected), claude mcp get fileforge, or run /mcp inside a session (it shows fileforge with its 4 tools). Remove with claude mcp remove fileforge.

Claude Desktop ​

  1. Open Settings → Developer → Edit Config (creates the file if missing), or edit it directly:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add the server:

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

  3. Fully quit and reopen Claude Desktop.

Verify: the tools (🔌/hammer) icon in the chat box lists FileForge's tools.

Cursor ​

  1. Create ~/.cursor/mcp.json (global, all projects) or .cursor/mcp.json (this project only):

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

  2. Open Settings → MCP (or Tools & Integrations) — toggle the server on if prompted.

Verify: the MCP settings panel shows fileforge with a green/connected dot and its tools listed.

Windsurf ​

  1. Create the config (Windsurf doesn't generate it on first launch):

    • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
    • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
    json
    {
  "mcpServers": {
    "fileforge": {
      "command": "npx",
      "args": ["-y", "@obrahaus/fileforge-mcp"],
      "env": { "FILEFORGE_API_KEY": "ff_live_YOUR_KEY" }
    }
  }
}

  2. In Cascade → MCP / Plugins, click Refresh.

Verify: fileforge appears in the Cascade MCP panel with its tools.

Any other MCP client ​

FileForge is a standard stdio MCP server. Point your client at:

json
{ "command": "npx", "args": ["-y", "@obrahaus/fileforge-mcp"], "env": { "FILEFORGE_API_KEY": "ff_live_YOUR_KEY" } }

Step 4 — Verify it works ​

Ask your agent something that only needs a read call, e.g.:

"Use FileForge to list the image formats I can convert a PNG to."

The agent should call list_formats and return targets like jpg, webp, gif, tiff, avif, and ico. If you see the tools but calls fail, jump to Troubleshooting.

Step 5 — Convert your first file ​

Just describe the conversion in natural language — the agent picks the tool and options:

"Convert ~/Desktop/logo.png into a favicon with sizes 16, 32, and 48."

The agent calls convert_file with target_format: "ico", options: { sizes: "16,32,48" }, and writes ~/Desktop/logo.ico. More examples:

  • "Make a 1200px-wide WebP of photo.jpg." → convert_file → webp, options: { width: 1200, quality: 82 }.
  • "Convert report.docx to PDF, keep only pages 1–3, and password-protect it." (Pro) → convert_file → pdf, options: { page_range: "1-3", password: "…" }.
  • "Convert every PNG in ./icons to WebP." → convert_files (bulk).
  • "Pull https://example.com/photo.jpg and convert it to AVIF." → convert_file with a url source.

The agent can also call list_formats first to discover valid targets/options, and get_conversion_status to resume a long job. See the tool reference for every input/output field.

Troubleshooting ​

SymptomCause & fix
config error: FILEFORGE_API_KEY … on startupThe key is missing or not ff_live_…. Re-check the env block.
401 unauthorized on a tool callThe key is invalid, revoked, or for the wrong environment. Rotate it / re-paste.
403 forbidden / pro_option on upload or convertMissing scope (most often files:write) or a free-tier key hitting a Pro feature. Re-issue the key with convert:write + files:write.
Tools don't appear / server "failed to connect"Run the command directly to see the real error: FILEFORGE_API_KEY=ff_live_… npx -y @obrahaus/fileforge-mcp (it should log … ready on stdio to stderr). Ensure Node ≥ 20.18.
First run is slow / times outnpx is downloading the package. In Claude Code, raise the timeout: MCP_TIMEOUT=60000 claude.
npx can't find @obrahaus/fileforge-mcpThe npm package isn't available to you — use the from-source option.
Targeting a non-production FileForge (e.g. develop)Add "FILEFORGE_API_BASE_URL": "https://fileforge-api.obrahaus-develop.aldrickb.xyz/v1" to the env block.
Where are the logs?The server logs to stderr only (stdout is the MCP protocol). Check your client's MCP/server logs. Set FF_MCP_LOG_LEVEL=debug for more detail.

Still stuck? The MCP server reference documents every tool, option, and environment variable, and Errors explains each API error code.

Built solo on dedicated metal.

© Obrahaus