@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)

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

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:

1. 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.
2. 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.
3. 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

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:

1. "Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it." → perceive_url
2. "Screenshot https://news.ycombinator.com and save the page as a PDF too." → perceive_url (both artifacts in one call)
3. "Search for the three best static site generators and read their homepages." → web_search with perceive_top
4. "Get every plan name and price from https://example.com/pricing." → extract_structured
5. "Convert /Users/me/Desktop/report.docx to PDF." → convert_document
6. "Convert /Users/me/Desktop/iphone.heic to webp." → convert_image
7. "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:

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

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