openai-mcp-server

Ein MCP-Server, der die OpenAI-API in jeden MCP-Client bringt — Claude Desktop, Claude Code, Cowork, Cursor oder alles andere, das das Protokoll spricht.

Neun Tools: Textgenerierung, Chat Completions, Modellentdeckung, Bildgenerierung und -bearbeitung, Transkription, Sprachsynthese, Embeddings und Moderation.

Warum es das gibt

Im Claude-Plugin-Katalog gibt es kein offizielles OpenAI-Plugin. Dieser Server ist das Äquivalent — ein normales Open-Source-Projekt, das Ihnen gehört und das Sie erweitern können.

Related MCP server: OpenAI Assistant MCP Server

Tools

Jedes Tool akzeptiert response_format: "markdown" | "json" — Markdown zum Lesen, JSON zur Verarbeitung. Alle Tools geben außerdem structuredContent zurück, sodass Clients, die Ausgabeschemata verstehen, typisierte Daten ohne Parsen erhalten.

Voraussetzungen

• Node.js 20 oder neuer

• Ein OpenAI-API-Schlüssel mit verfügbarem Kontingent

Installation

git clone <your-repo-url> openai-mcp-server
cd openai-mcp-server
npm install
npm run build

Build prüfen:

node dist/index.js --version   # prints 1.0.0
node dist/index.js --help      # lists all environment variables

MCP-Client konfigurieren

Der Server spricht MCP über stdio, daher startet der Client ihn als Unterprozess.

Claude Desktop

Bearbeiten Sie claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openai": {
      "command": "node",
      "args": ["/absolute/path/to/openai-mcp-server/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_MCP_OUTPUT_DIR": "/Users/you/openai-mcp-output"
      }
    }
  }
}

Starten Sie Claude Desktop danach neu.

Claude Code

claude mcp add openai \
  --env OPENAI_API_KEY=sk-proj-... \
  -- node /absolute/path/to/openai-mcp-server/dist/index.js

Jeder andere MCP-Client

Richten Sie ihn auf node /absolute/path/to/dist/index.js mitsamt OPENAI_API_KEY in der Umgebung.

Konfiguration

Nur OPENAI_API_KEY ist erforderlich. Siehe .env.example für eine kopierbare Vorlage.

Modell-IDs ändern sich. OpenAI fügt Modelle hinzu, benennt sie um und stellt sie ein, und der Zugriff ist je nach Projekt unterschiedlich. Jeder Standardwert ist übersteuerbar, und openai_list_models zeigt, was Ihr Schlüssel tatsächlich erreichen kann — bei einem Fehler "model not found" beginnen Sie hier.

Sicherheitsmodell

Zwei bewusste Einschränkungen:

Das Dateisystem ist eine Sandbox. Tools, die lokale Dateien lesen (openai_edit_image, openai_transcribe_audio), akzeptieren nur absolute Pfade innerhalb von OPENAI_MCP_ALLOWED_DIRS. Pfade werden vor der Prüfung mit realpath kanonisiert, sodass Symlinks und ../-Traversionen nicht entkommen können. Das Ausgabeverzeichnis ist immer erlaubt; für alles andere müssen Sie es freigeben. Halten Sie diese Liste eng.

Binärausgaben gelangen nie ins Gespräch. Bilder, Audio und Embedding-Vektoren werden auf die Festplatte geschrieben, und nur ihre Pfade werden zurückgegeben. Ein einzelnes Base64-PNG oder ein 3072-Float-Vektor würde sonst das Kontextfenster des Modells überfluten.

Der API-Schlüssel wird ausschließlich aus der Umgebung gelesen — er erscheint nie in einem Tool-Argument, einer Logzeile oder einer Fehlermeldung.

Beispiele

Stellen Sie Ihrem MCP-Client die Frage in einfacher Sprache; er wählt das passende Tool.

„Verwende den OpenAI-Server, um diesen Text in drei Sätzen zusammenzufassen."

→ openai_generate_text

„Welche OpenAI-Embedding-Modelle kann ich verwenden?"

→ openai_list_models und filter="embedding"

„Erzeuge ein transparentes PNG-Logo eines blauen Fuchses."

→ openai_generate_image und background="transparent"

„Transkriptiere ~/Documents/audio/interview.m4a auf Deutsch."

→ openai_transcribe_audio und language="de" — das Verzeichnis muss in OPENAI_MCP_ALLOWED_DIRS enthalten sein.

„Bette diese 40 Produktbeschreibungen ein, damit ich sie aggregieren kann."

→ openai_create_embeddings, dann die JSON-Datei lesen, die gemeldet wird

Entwicklung

npm run dev        # watch mode via tsx
npm run typecheck  # tsc --noEmit, strict
npm test           # unit tests, no network calls
npm run build      # compile to dist/

Die Testsabdeckung umfasst das Konfigurations-Parsing, die Dateisystem-Sandbox (einschließlich Symlink-Escape und Traversal), die Fehlerformatierung und das Aufbereiten von Antworten. Die Tests nehmen nie Kontakt zur OpenAI-API auf.

Projektstruktur

src/
├── index.ts          entry point, server assembly, CLI flags
├── config.ts         environment parsing and validation
├── client.ts         OpenAI client construction
├── constants.ts      defaults, limits, response formats
├── errors.ts         API errors → actionable agent messages
├── files.ts          sandboxed read/write
├── format.ts         tool result shaping, character limit
└── tools/
    ├── text.ts       generate_text, chat_completion
    ├── models.ts     list_models
    ├── images.ts     generate_image, edit_image
    ├── audio.ts      transcribe_audio, text_to_speech
    └── analysis.ts   create_embeddings, moderate_content

Ein Tool hinzufügen

1. Schreiben Sie ein Zod-Schema mit .strict() und einer .describe() für jedes Feld.

2. Registrieren Sie es mit server.registerTool(name, config, handler) — einschließlich title, description, inputSchema, outputSchema und annotations.

3. Geben Sie über toolResult(...) zurück, damit Markdown-/JSON-Behandlung und das Zeichenlimit konsistent bleiben; Fehler fangen Sie mit errorResult(...) ab.

4. Fügen Sie den Registrierungsaufruf in src/index.ts und einen Test in test/ hinzu.

Troubleshooting

Der Server loggt nach stderr; stdout trägt den JSON-RPC-Stream und muss sauber bleiben.

Lizenz

MIT — siehe LICENSE.