MCP-Server-Einrichtung und JSON-Konfiguration#

@enconvert/mcp ist der offizielle Model Context Protocol (MCP)-Server für EnConvert. Er ermöglicht es jedem MCP-kompatiblen KI-Assistenten (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code, Zed, Gemini CLI, Codex, OpenCode), Webseiten und Dateien direkt aus dem Chat zu rendern, zu durchsuchen, zu extrahieren, einzulesen, zu überwachen, zu konvertieren und zu komprimieren. Richte ihn mit einem einzigen Befehl ein, npx @enconvert/mcp setup, oder kopiere den exakten JSON-Config-Block für die MCP-Config-Datei deines Clients. Er läuft lokal über stdio auf Node.js 18+ und registriert vierundzwanzig Tools.

Was ist MCP?#

Das Model Context Protocol ist ein offener Standard, um Tools, Prompts und Ressourcen über eine schlanke JSON-RPC-Schnittstelle für LLM-gestützte Assistenten bereitzustellen. Ein MCP-Server läuft als lokaler Subprozess, der Assistent startet ihn beim Sitzungsstart, und die Tools werden zu vollwertigen Fähigkeiten, die das Modell während einer Konversation aufrufen kann.

@enconvert/mcp ist ein schlanker Wrapper um das Node.js SDK. Es registriert vierundzwanzig Tools, jedes mit einer Beschreibung, die auf zuverlässige LLM-Tool-Auswahl abgestimmt ist. Alle HTTP-, Authentifizierungs-, Timeout- und Recovery-Polling-Mechanismen werden vom SDK übernommen.

Voraussetzungen#

• Node.js 18 oder neuer auf dem Rechner, auf dem der Assistent läuft
• Ein privater EnConvert-API-Key (sk_...), den du im Dashboard erstellst

Installation: ein Befehl#

npx @enconvert/mcp setup

Der interaktive Einrichtungsassistent erledigt alles:

1. Erkennt deine KI-Tools (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) und lässt dich auswählen, welche davon EnConvert erhalten (erkannte Tools sind vorausgewählt).
2. Fragt einmalig nach deinem geheimen API-Key (verdeckte Eingabe) und validiert ihn live gegen die API. Versehentlich einen öffentlichen Key eingefügt? Das wird dir genau mitgeteilt.
3. Schreibt jede Config korrekt, einschließlich des cmd /c npx-Wrappers, den natives Windows benötigt.

$ 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_..., 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.

Genauso einfach verwalten#

Für Skripting überspringt setup --clients claude-code,cursor --api-key sk_... --yes jede Eingabeaufforderung. Wird rotate-key ohne Argument ausgeführt, erfolgt die Eingabe verdeckt, sodass der Key nie in deiner Shell-History landet.

Wo der Key gespeichert wird#

setup speichert deinen Key einmal in ~/.enconvert/config.json (Dateimodus 600), statt ihn in der Klartext-Config jedes einzelnen Clients zu duplizieren. Der Server liest ihn beim Start; die Umgebungsvariable ENCONVERT_API_KEY überschreibt ihn immer (für Docker, CI oder manuelle Setups). Das Rotieren eines Keys ist daher eine Änderung an nur einer Datei, und jeder Client übernimmt sie beim nächsten Start.

Fortgeschritten: manuelle Konfiguration#

Möchtest du es lieber manuell verdrahten? Füge dies zur MCP-Config deines Clients hinzu (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Claude Desktops claude_desktop_config.json, ...):

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

Ersetze unter nativem Windows command durch cmd und stelle "/c", "npx" args voran, denn nacktes npx hängt sich auf. Für Claude Code:

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

Der inline env-Block ist optional, wenn du setup bereits ausgeführt hast, da der Server automatisch auf den gespeicherten Key zurückgreift.

Verfügbare Tools#

Vierundzwanzig Tools. Sämtliche URL-/Browser-Arbeit läuft über die V2-Tools (perceive_url und Verwandte); die Datei-Tools decken lokale und Remote-Arbeit mit Dokumenten, Bildern und Komprimierung ab.

Tool-Beschreibungen folgen einer konsistenten Struktur aus Verwenden, wenn / NICHT verwenden, wenn / Rückgabe, damit der Assistent Prompts an das richtige Tool weiterleitet. Die V2-Tools erfordern den privaten API-Key und sind je nach Tarif freigeschaltet, sodass ein deaktiviertes Feature oder ausgeschöpftes Kontingent eine klare Kontingent-Meldung liefert statt eines kryptischen Fehlers.

Zwei Verhaltensweisen solltest du kennen, bevor du danach fragst. compress_image ändert das Format nie (ein PNG kommt als PNG zurück, ein JPEG als JPEG) und liefert nie eine Datei, die größer ist als die Eingabe, lässt sich also gefahrlos auf eine bereits optimierte Datei anwenden; target_size_kb ist ein Best-Effort-Ziel, und ein Budget, das sich nicht erreichen lässt, liefert die kleinste erzielte Datei statt eines Fehlers, prüfe also die zurückgegebene Dateigröße. Bei convert_image gelten width und height nur für SVG-Eingaben und akzeptieren jeweils 1 bis 10000: Wird nur einer der beiden Werte übergeben, skaliert die Ausgabe proportional zum Seitenverhältnis des SVG, während beide zusammen die Ausgabegröße exakt festlegen.

Konfiguration#

Der API-Key wird in dieser Reihenfolge aufgelöst:

1. Umgebungsvariable ENCONVERT_API_KEY (aus der MCP-Config des Assistenten), die immer gewinnt
2. ~/.enconvert/config.json, geschrieben von npx @enconvert/mcp setup

Beispiel-Prompts#

Probiere nach der Installation Folgendes in einer neuen Assistenten-Sitzung aus:

Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it.

Screenshot https://news.ycombinator.com and save the page as a PDF too.

Search for the three best static site generators and read their homepages.

Get every plan name and price from https://example.com/pricing.

Convert /Users/me/Desktop/report.docx to PDF.

Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format.

Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index.

Watch https://example.com/changelog and tell me when it changes.

Der Assistent wählt automatisch das richtige Tool: URL-Arbeit landet bei perceive_url, Suche bei web_search, strukturiertes Scraping bei extract_structured, Größenbudgets bei compress_image, RAG-taugliches Markdown bei convert_anything_to_markdown und die übrige Datei-Arbeit bei den Convert-Tools.

Ausgabeformat#

Jedes Tool liefert eine konsistente Antwort:

• Eine Textzusammenfassung mit Download-URLs und Metadaten
• Ein structuredContent-Block mit dem vollständigen typisierten Ergebnis
• Ein resource_link zur lokalen Datei, wenn save_to angegeben ist (Datei-Tools)
• Bei perceive_url wird das Markdown-Artefakt zusätzlich inline in der Antwort mitgeliefert (bis zu ~256 KB), sodass der Assistent lesen und zusammenfassen kann, ohne einen separaten Abruf durchzuführen

Funktionsweise#

@enconvert/mcp ruft über das Node.js SDK dieselben öffentlichen REST-Endpunkte auf, die im Rest dieser Seite dokumentiert sind. Das bedeutet:

• Gleiches Wire-Format: jedes Tool bildet 1:1 auf einen /v1/convert/*- oder /v2/*-Endpunkt ab
• Gleiche Timeout-Recovery: lange Konvertierungen fallen automatisch und transparent auf job_id-Polling zurück
• Gleiche Authentifizierung: dein privater API-Key autorisiert jeden Call, und deine Dashboard-Kontingente und Rate-Limits gelten

Der Assistent sieht den API-Key nie. Er sieht nur die Tool-Liste und die Tool-Eingaben.

Fehlerbehebung#

Der Assistent versucht, einen lokalen Browser statt des MCP-Tools zu verwenden. Der MCP-Server ist nicht registriert oder nicht gestartet. Führe npx @enconvert/mcp status in einem regulären Terminal aus und starte den Assistenten anschließend neu.

Authentication failed: Invalid or missing API key. Führe npx @enconvert/mcp status aus. Der Befehl zeigt, woher der Key stammt, und validiert ihn live. Behebe es mit npx @enconvert/mcp rotate-key.

npx hängt sich unter nativem Windows auf. Verwende cmd /c npx .... npx @enconvert/mcp setup schreibt diesen Wrapper unter Windows automatisch.

Der Tool-Call läuft in ein Timeout, bevor die Konvertierung abgeschlossen ist. Aufwändige Browser-Renderings können 30+ Sekunden dauern. Das SDK wartet standardmäßig bis zu 5 Minuten; erhöhe das Per-Tool-Timeout des Assistenten, falls es früher abbricht.

Relativer Pfad bei convert_document / convert_image abgelehnt. Übergib einen absoluten Pfad (z. B. /Users/me/file.docx oder C:\Users\me\file.docx) oder eine http(s)://-URL. MCP-Server haben kein verlässliches Arbeitsverzeichnis.

Quellen und Links#

• npm: @enconvert/mcp
• GitHub: enconvert/mcp
• Lizenz: MIT
• Zugrunde liegendes SDK: Node.js SDK
• MCP-Spezifikation: modelcontextprotocol.io

Häufig gestellte Fragen#

Wie konfiguriere ich einen MCP-Server in JSON?#

Füge in der MCP-Config-Datei deines Clients einen Eintrag unter mcpServers hinzu (~/.cursor/mcp.json für Cursor, ~/.codeium/windsurf/mcp_config.json für Windsurf, claude_desktop_config.json für Claude Desktop) mit "command": "npx", "args": ["-y", "@enconvert/mcp@latest"] und deinem ENCONVERT_API_KEY im env-Block. Oder überspringe manuelles JSON komplett: npx @enconvert/mcp setup erkennt deine installierten KI-Tools und schreibt jede Config korrekt.

Wie richte ich einen MCP-Server in Claude Code ein?#

Führe claude mcp add enconvert -s user -e ENCONVERT_API_KEY=sk_your_key -- npx -y @enconvert/mcp@latest aus, oder nutze den interaktiven Assistenten npx @enconvert/mcp setup, der Claude Code erkennt und automatisch konfiguriert. Starte den Assistenten danach vollständig neu, denn MCP-Server werden nur beim Start einer Sitzung geladen.

Warum hängt sich npx beim Starten eines MCP-Servers unter Windows auf?#

Nacktes npx hängt sich unter nativem Windows auf. Ersetze command durch cmd und stelle "/c", "npx" args voran; npx @enconvert/mcp setup schreibt diesen Wrapper unter Windows automatisch.

Wo speichert der MCP-Server meinen API-Key?#

npx @enconvert/mcp setup speichert den Key einmal in ~/.enconvert/config.json (Dateimodus 600), statt ihn in der Klartext-Config jedes einzelnen Clients zu duplizieren. Die Umgebungsvariable ENCONVERT_API_KEY überschreibt ihn immer, und npx @enconvert/mcp rotate-key ersetzt den gespeicherten Key mit einem einzigen Befehl für jeden Client.

Kann ein KI-Assistent Dateien über einen MCP-Server konvertieren?#

Ja. Das Tool convert_document konvertiert DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML und TOML zwischen Formaten (standardmäßig PDF). EPUB hat kein convert_document-Paar; schicke .epub-Dateien durch convert_anything_to_pdf oder convert_anything_to_markdown. Außerdem konvertiert convert_image zwischen JPEG, PNG, SVG, HEIC und WebP, plus PDF-zu-JPEG-Rasterung. Übergib absolute Dateipfade oder http(s)://-URLs, da MCP-Server kein verlässliches Arbeitsverzeichnis haben.

Wie verkleinere ich ein Bild, ohne sein Format zu ändern?#

Bitte den Assistenten, die Datei zu komprimieren, dann leitet er an compress_image weiter: Ein PNG bleibt ein PNG, ein JPEG ein JPEG und ein WebP ein WebP. Metadaten werden entfernt, ICC-Profil und EXIF-Ausrichtung bleiben erhalten, und die Datei ist nie größer als die Eingabe. Gib zusätzlich ein target_size_kb-Budget an, dann wird unter Beibehaltung des Seitenverhältnisses herunterskaliert, bis das Budget erreicht ist; ein nicht erreichbares Budget liefert die kleinste erzielte Datei statt eines Fehlers, prüfe also die zurückgegebene Größe.