--- seo_title: MCP-Server JSON-Konfiguration: Claude Code, Cursor | EnConvert meta_desc: Richte den @enconvert/mcp-Server in Claude Code, Cursor, Windsurf und Claude Desktop ein, mit exakter JSON-Config oder einem Befehl: npx @enconvert/mcp setup. keywords: mcp server json konfigurieren, mcp server dateikonvertierung, claude code mcp server einrichten, cursor mcp json config, claude desktop mcp server installieren, windsurf mcp konfiguration, npx mcp server setup, model context protocol dateikonverter, enconvert mcp server, mcp tool bildkomprimierung, mcp pdf zu markdown für rag --- # 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.
npm: @enconvert/mcp · Quelle: enconvert/mcp · Node: 18+ · Transport: stdio
--- ## Was ist MCP? Das [Model Context Protocol](https://modelcontextprotocol.io) 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](/de/docs/guides/integrations/sdks/nodejs.md). 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](/de/dashboard) erstellst --- ## Installation: ein Befehl ```bash 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. ```text $ 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. ```
Neustart erforderlich. MCP-Server werden nur beim Start einer Assistenten-Sitzung geladen. Beende den Assistenten nach der Einrichtung vollständig und öffne ihn neu, bevor du testest.
### Genauso einfach verwalten | Befehl | Was er macht | |---------|-------------| | `npx @enconvert/mcp status` | Zeigt, wo der Server installiert ist, und validiert deinen Key live | | `npx @enconvert/mcp rotate-key` | Ersetzt den gespeicherten API-Key mit einem Befehl, gültig für jeden Client | | `npx @enconvert/mcp remove` | Deinstalliert aus ausgewählten Tools (löscht optional den gespeicherten Key) | | `npx @enconvert/mcp setup --yes` | Nicht-interaktiv: konfiguriert alle erkannten Tools mit dem gespeicherten Key | | `npx @enconvert/mcp upgrade` | Prüft npm auf eine neuere Version und installiert sie. Mit `--dry-run` nur als Vorschau | 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`, ...): ```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: ```bash 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 | Zweck | |------|---------| | `perceive_url` | Rendert eine Live-Seite in mehrere Artefakte gleichzeitig: Markdown (inline), HTML, Screenshots, PDF, Links, Bilder, plus strukturierte Extraktion, mit ~1 Std. Caching | | `get_perceive_operation` / `perceive_batch` / `get_perceive_batch` | Signiert Artefakt-URLs neu; rendert bis zu 1000 URLs in einem Batch; fragt Batches ab | | `discover_urls` | Listet die URLs einer Site via sitemap/crawl/hybrid auf, ganz ohne Rendering | | `web_search` | Google-gestützte Suche in sechs Kategorien, mit optionalem Auto-Rendering der Top-Ergebnisse | | `extract_structured` | Schema-gesteuerte Datenextraktion (kostenloser CSS-Durchlauf + LLM-Eskalation) aus bis zu 50 URLs | | `start_ingest` + Job-Tools | Wandelt eine Site oder URL-Liste in RAG-taugliches, gechunktes JSONL um (asynchron), mit list/get/cancel/webhook-retry | | `create_watcher` + Watcher-Tools | Überwacht Seiten auf Änderungen im Stunden-Plus-Takt, mit Diff-Historie, list/get/update/delete | | `convert_document` | Konvertiert DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML, TOML zwischen Formaten (standardmäßig PDF) | | `convert_image` | Konvertiert zwischen JPEG, PNG, SVG, HEIC, WebP, plus PDF → JPEG-Rasterung, mit optionalem `width` und `height`, um die Ausgabegröße beim Rastern von SVG festzulegen | | `compress_image` | Verkleinert ein PNG, JPEG oder WebP an Ort und Stelle, Format unverändert, optional bis auf eine Zielgröße in KB | | `convert_anything_to_markdown` | Wandelt PDF-, Office-, ODF-, EPUB-, HTML-, CSV- oder Textdateien in sauberes Markdown mit erhaltener Überschriftenhierarchie für RAG-Pipelines um | | `convert_anything_to_pdf` | Wandelt nahezu jede Datei in ein PDF um: Office, ODF, iWork, Bilder, SVG, HTML, Markdown, EPUB, RTF, CSV, plus PDF-Passthrough | | `get_job_status` | Prüft einen Dateikonvertierungs-Job anhand seiner Job-ID | 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` | Einstellung | Erforderlich | Standard | Zweck | |----------|----------|---------|---------| | `ENCONVERT_API_KEY` (env) oder `api_key` (Config-Datei) | Ja | -- | Privater API-Key (`sk_...`) | | `ENCONVERT_BASE_URL` (env) oder `base_url` (Config-Datei) | Nein | `https://api.enconvert.com` | Override für Staging oder selbst gehostete Gateways |
Füge niemals einen Key in den Assistenten-Chat ein. Nutze npx @enconvert/mcp setup (verdeckte Eingabe), oder setze ihn über den env-Block in der MCP-Config-Datei. Keys, die im Chat-Verlauf landen, enden in Transkripten.
--- ## Beispiel-Prompts Probiere nach der Installation Folgendes in einer neuen Assistenten-Sitzung aus: ```text Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it. ``` ```text Screenshot https://news.ycombinator.com and save the page as a PDF too. ``` ```text Search for the three best static site generators and read their homepages. ``` ```text Get every plan name and price from https://example.com/pricing. ``` ```text Convert /Users/me/Desktop/report.docx to PDF. ``` ```text Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format. ``` ```text Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index. ``` ```text 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](/de/docs/guides/integrations/sdks/nodejs.md) 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](https://www.npmjs.com/package/@enconvert/mcp) - **GitHub**: [enconvert/mcp](https://github.com/enconvert/mcp) - **Lizenz**: MIT - **Zugrunde liegendes SDK**: [Node.js SDK](/de/docs/guides/integrations/sdks/nodejs.md) - **MCP-Spezifikation**: [modelcontextprotocol.io](https://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.