@enconvert/mcp

@enconvert/mcp

Official Model Context Protocol (MCP) server for Enconvert — lets any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, Claude Desktop, Continue, etc.) convert files and URLs through a single command.

What you get

Twenty-one tools, optimized for reliable LLM tool selection. All URL/browser work goes through the V2 tools (perceive_url and friends); the V1 tools cover local/remote FILE conversion.

File conversion (3)

Tool	What it does
convert_document	Convert DOC(X), XLS(X), PPT(X), ODT, ODS, ODP, OTS, Pages, Numbers, EPUB, HTML, MD, CSV, JSON, XML, YAML, TOML to PDF (or between each other)
convert_image	Convert between JPEG, PNG, SVG, HEIC, WebP — plus PDF → JPEG rasterization (handy for iPhone HEIC → WebP)
get_job_status	Check a single file-conversion job by its job ID

V2 — web data for agents (18, private API key required, plan-gated)

Tool	What it does
perceive_url	Render a page into multiple artifacts at once (markdown, HTML, screenshots, PDF, links, images) + structured extraction, with ~1h caching
get_perceive_operation	Re-fetch a perceive result with freshly signed artifact URLs
perceive_batch	Perceive up to 1000 URLs with shared options (inline for small batches, async for large)
get_perceive_batch	Poll a perceive batch by job ID
discover_urls	Enumerate a site's URLs via sitemap/crawl/hybrid — no rendering, no render quota
web_search	Google-backed search (web, news, images, scholar, patents, maps) with optional auto-perceive of top results
extract_structured	Schema-driven data extraction (free CSS pass + LLM escalation) from up to 50 URLs or a discovered site
start_ingest	Turn a site or URL list into RAG-ready chunked JSONL (always async)
list_ingest_jobs / get_ingest_job / cancel_ingest_job	Manage ingest jobs
retry_ingest_webhook	Re-deliver a completed job's HMAC-signed completion webhook
create_watcher / list_watchers / get_watcher / get_watcher_snapshots / update_watcher / delete_watcher	Monitor pages for changes on an hourly-plus cadence with diff history and notifications

Not exposed by design: the webhook signing-secret endpoints (GET/POST /v2/ingest/webhook-secret*) — secrets do not belong in LLM context. Fetch those from the Enconvert dashboard.

Requirements

• Node.js 18 or later
• An Enconvert API key — get one at enconvert.com/dashboard/api-keys

Install — one command

npx @enconvert/mcp setup

That's it. The wizard:

• Detects your AI tools (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) and lets you pick which get Enconvert — detected tools are preselected.
• Asks for your secret API key once (hidden input) and validates it live against the API — it even tells you if you pasted a public key by mistake.
• Writes every config correctly, including the cmd /c npx wrapper Windows needs. Your key is stored once in ~/.enconvert/config.json (permissions 600) — never copied into client configs.

$ npx @enconvert/mcp setup

  Enconvert MCP - setup

? Which AI tools should get Enconvert?
  [x] Claude Code (detected)    [x] Cursor (detected)
  [ ] Claude Desktop            [ ] Windsurf   ...
? Paste your SECRET API key (sk_live_..., input hidden): ********
  ✔ API key is valid.
  + Claude Code - claude CLI (user scope)
  + Cursor - ~/.cursor/mcp.json

  Done. Restart your AI tools to pick up the server.

Restart your AI tools afterwards, and you're running.

Manage it just as easily

Command	What it does
npx @enconvert/mcp status	Where it's installed + whether your key is valid (live check)
npx @enconvert/mcp rotate-key	Swap in a new API key — one command, applies to every client
npx @enconvert/mcp remove	Uninstall from selected tools (optionally delete the saved key)
npx @enconvert/mcp setup --yes	Non-interactive: configure all detected tools with the saved key

Scripting? setup --clients claude-code,cursor --api-key sk_live_... --yes skips all prompts. rotate-key with no argument prompts with hidden input so the key never lands in your shell history.

Where the key lives

setup stores your key once in ~/.enconvert/config.json (mode 600) instead of pasting it into every client's plaintext config. The server reads it at startup; the ENCONVERT_API_KEY environment variable always overrides it (for Docker, CI, or manual setups). Rotating is therefore a single-file change — every client picks it up on its next launch.

Advanced: manual configuration

Prefer to wire it yourself? Add this to your client's MCP config (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, etc.):

{
  "mcpServers": {
    "enconvert": {
      "command": "npx",
      "args": ["-y", "@enconvert/mcp@latest"],
      "env": {
        "ENCONVERT_API_KEY": "sk_live_your_key"
      }
    }
  }
}

On native Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "@enconvert/mcp@latest"] — bare npx hangs. (WSL behaves like Linux.) For Claude Code:

claude mcp add enconvert -s user \
  -e ENCONVERT_API_KEY=sk_live_your_key \
  -- npx -y @enconvert/mcp@latest

The inline env block is optional if you've run setup (or created ~/.enconvert/config.json) — the server falls back to the saved key automatically. Client config locations: Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows); Cursor ~/.cursor/mcp.json; Windsurf ~/.codeium/windsurf/mcp_config.json; Gemini CLI ~/.gemini/settings.json; Codex ~/.codex/config.toml.

Try it

Once installed, try any of these in a fresh prompt:

• "Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it." → perceive_url
• "Screenshot https://news.ycombinator.com and save the page as a PDF too." → perceive_url (both artifacts in one call)
• "Search for the three best static site generators and read their homepages." → web_search with perceive_top
• "Get every plan name and price from https://example.com/pricing." → extract_structured
• "Convert /Users/me/Desktop/report.docx to PDF." → convert_document
• "Convert /Users/me/Desktop/iphone.heic to webp." → convert_image
• "Watch https://example.com/changelog and tell me when it changes." → create_watcher

The agent picks the right tool automatically — descriptions are tuned so URL work lands on perceive_url and file work on the convert tools.

Configuration

The API key is resolved in this order:

• ENCONVERT_API_KEY environment variable (from your MCP client's env block) — always wins
• ~/.enconvert/config.json, written by npx @enconvert/mcp setup

Setting	Required	Default	Purpose
ENCONVERT_API_KEY (env) or api_key (config file)	✅ Yes	—	Your secret Enconvert API key
ENCONVERT_BASE_URL (env) or base_url (config file)	No	https://api.enconvert.com	Override for staging or self-hosted Enconvert

How it works

The server is a thin MCP wrapper around the official @enconvert/node-sdk — which owns all HTTP, auth, timeout (5 min), and job-polling fallback logic. Each tool handler maps MCP input to an SDK call and returns a consistent response:

• a text summary with the download URL(s) and metadata
• a structuredContent block with the full typed result
• a resource_link to the local file when save_to is provided (file tools)
• for perceive_url, the markdown artifact inlined in the response (up to ~256 KB) so agents can immediately read it without a second HTTP fetch

Troubleshooting

npx hangs on native Windows Use cmd /c npx … — the cmd shim handles Windows path resolution that bare npx does not. (npx @enconvert/mcp setup writes this automatically on Windows.)

Authentication failed: Invalid or missing API key Run npx @enconvert/mcp status — it shows where your key comes from and validates it live. Fix with npx @enconvert/mcp rotate-key, or check the ENCONVERT_API_KEY env block if you configured manually.

Tool call times out Browser renders of heavy pages (perceive_url, extract_structured) can take 15–30 s, and the SDK waits up to 5 min. If your client has a shorter timeout, raise it.

"Relative path" error on convert_document / convert_image Pass an absolute path (e.g., /Users/me/file.docx or C:\Users\me\file.docx), or pass an http(s):// URL. MCP servers have no reliable working directory.

How it depends on the Node SDK

This MCP server is a thin wrapper around @enconvert/node-sdk, which owns all HTTP, authentication, timeout, retry, and job_id polling-on-500 logic. New SDK releases automatically benefit the MCP server.

License

MIT

Links

• Enconvert website — https://enconvert.com
• Enconvert Node SDK — https://www.npmjs.com/package/@enconvert/node-sdk
• MCP specification — https://modelcontextprotocol.io
• Issues / feedback — https://github.com/enconvert/enconvert-mcp/issues