@obrahaus/fileforge-mcp

A Model Context Protocol server that lets AI agents convert files with FileForge — images, audio, video, documents, and archives — without learning the REST API. It's a thin client of the FileForge Public API (/v1): same ff_live_… keys, tiers, and limits. No native dependencies.

Install

Add to your MCP client config and set your API key:

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

• Claude Code: claude mcp add fileforge -e FILEFORGE_API_KEY=ff_live_… -- npx -y @obrahaus/fileforge-mcp
• Claude Desktop / Cursor / Windsurf: paste the block above into the app's MCP config.

Get an API key from your FileForge account → Settings → API keys (Forge Pro).

Tools

• convert_file — one call: give it a file (source.path local file, source.url, or base64 source.bytes) + target_format (+ optional preset, options, output); it uploads, converts, polls, and downloads.
• list_formats — the tier-filtered formats + options matrix.
• get_conversion_status — poll/resume a conversion and download its result.
• convert_files — bulk conversion (Forge Pro).

Example: "Convert ./logo.png to a favicon with sizes 16,32,48" → convert_file({ source: { path: "./logo.png" }, target_format: "ico", options: { sizes: "16,32,48" } }) → writes ./logo.ico.

Configuration

| Env var | Default | Purpose | |---------|---------|---------| | FILEFORGE_API_KEY | — (required) | Your ff_live_… key. | | FILEFORGE_API_BASE_URL | https://fileforge-api.obrahaus.com/v1 | Override for self-host / dev. | | FF_MCP_MAX_POLL_SECONDS | 300 | Ceiling on any tool's wait loop. | | FF_MCP_MAX_INLINE_BYTES | 5242880 | Max size for base64-inlined results. | | FF_MCP_OUTPUT_DIR | — | Default output directory. | | FF_MCP_LOG_LEVEL | info | Log verbosity. |

Troubleshooting

• Logs go to stderr, never stdout — stdout is reserved for the JSON-RPC protocol. Check your MCP client's server logs for [fileforge-mcp] lines.
• config error: FILEFORGE_API_KEY … — the key is missing/malformed; it must look like ff_live_….
• Self-host / develop — set FILEFORGE_API_BASE_URL to your API's /v1 base.
• First run — use npx -y so npm installs without an interactive prompt.

Develop (from a checkout)

pnpm --filter @obrahaus/fileforge-mcp build       # bundles dist/index.js
FILEFORGE_API_KEY=ff_live_… node apps/mcp/dist/index.js
# or, without building: pnpm --filter @obrahaus/fileforge-mcp dev

Full docs: https://fileforge-docs.obrahaus.com/api/mcp