OpenAPI MCP-Server

Ein Model Context Protocol (MCP)-Server, der OpenAPI-Endpunkte als MCP-Ressourcen bereitstellt. Dieser Server ermöglicht Large Language Models die Erkennung und Interaktion mit REST-APIs, die in OpenAPI-Spezifikationen über das MCP-Protokoll definiert sind.

Überblick

Dieser MCP-Server unterstützt zwei Transportmethoden:

Stdio-Transport (Standard): Für die direkte Integration mit KI-Systemen wie Claude Desktop, die MCP-Verbindungen über Standard-Eingabe/Ausgabe verwalten.
Streamable HTTP Transport : Für die Verbindung mit dem Server über HTTP, sodass Webclients und andere HTTP-fähige Systeme das MCP-Protokoll verwenden können.

Related MCP server: File Context MCP

Schnellstart für Benutzer

Option 1: Verwendung mit Claude Desktop (Stdio Transport)

Dieses Repository muss nicht geklont werden. Konfigurieren Sie Claude Desktop einfach für die Verwendung dieses MCP-Servers:

Suchen oder erstellen Sie Ihre Claude Desktop-Konfigurationsdatei:
- Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Fügen Sie die folgende Konfiguration hinzu:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

Ersetzen Sie die Umgebungsvariablen durch Ihre tatsächliche API-Konfiguration:
- API_BASE_URL : Die Basis-URL Ihrer API
- OPENAPI_SPEC_PATH : URL oder Pfad zu Ihrer OpenAPI-Spezifikation
- API_HEADERS : Durch Kommas getrennte Schlüssel:Wert-Paare für API-Authentifizierungsheader

Option 2: Verwendung mit HTTP-Clients (HTTP-Transport)

So verwenden Sie den Server mit HTTP-Clients:

Keine Installation erforderlich! Verwenden Sie npx, um das Paket direkt auszuführen:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

Interagieren Sie mit dem Server über HTTP-Anfragen:

# Initialize a session (first request)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"client":{"name":"curl-client","version":"1.0.0"},"protocol":{"name":"mcp","version":"2025-03-26"}}}'

# The response includes a Mcp-Session-Id header that you must use for subsequent requests
# and the InitializeResult directly in the POST response body.

# Send a request to list tools
# This also receives its response directly on this POST request.
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Open a streaming connection for other server responses (e.g., tool execution results)
# This uses Server-Sent Events (SSE).
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# Example: Execute a tool (response will arrive on the GET stream)
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# Terminate the session when done
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

Transportarten

Stdio-Transport (Standard)

Der stdio-Transport ist für die direkte Integration mit KI-Systemen wie Claude Desktop konzipiert, die MCP-Verbindungen über Standard-Ein-/Ausgabe verwalten. Dies ist die einfachste Einrichtung und erfordert keine Netzwerkkonfiguration.

Wann zu verwenden : Bei der Integration mit Claude Desktop oder anderen Systemen, die stdio-basierte MCP-Kommunikation unterstützen.

Streambarer HTTP-Transport

Der HTTP-Transport ermöglicht den Zugriff auf den MCP-Server über HTTP und ermöglicht Webanwendungen und anderen HTTP-fähigen Clients die Interaktion mit dem MCP-Protokoll. Er unterstützt Sitzungsverwaltung, Streaming-Antworten und Standard-HTTP-Methoden.

Hauptmerkmale :

Sitzungsverwaltung mit Mcp-Session-Id-Header
HTTP-Antworten für initialize und tools/list werden synchron beim POST gesendet.
Andere Server-zu-Client-Nachrichten (z. B. tools/execute Ausführungsergebnisse, Benachrichtigungen) werden mithilfe von Server-Sent Events (SSE) über eine GET-Verbindung gestreamt.
Unterstützung für POST/GET/DELETE-Methoden

Wann zu verwenden : Wenn Sie den MCP-Server Webclients oder Systemen zugänglich machen müssen, die über HTTP statt über stdio kommunizieren.

Konfigurationsoptionen

Der Server kann über Umgebungsvariablen oder Befehlszeilenargumente konfiguriert werden:

Umgebungsvariablen

API_BASE_URL – Basis-URL für die API-Endpunkte
OPENAPI_SPEC_PATH – Pfad oder URL zur OpenAPI-Spezifikation
API_HEADERS – Komma-getrennte Schlüssel:Wert-Paare für API-Header
SERVER_NAME – Name für den MCP-Server (Standard: „mcp-openapi-server“)
SERVER_VERSION – Version des Servers (Standard: „1.0.0“)
TRANSPORT_TYPE – Zu verwendender Transporttyp: „stdio“ oder „http“ (Standard: „stdio“)
HTTP_PORT – Port für HTTP-Transport (Standard: 3000)
HTTP_HOST – Host für HTTP-Transport (Standard: „127.0.0.1“)
ENDPOINT_PATH – Endpunktpfad für HTTP-Transport (Standard: „/mcp“)

Befehlszeilenargumente

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp

Sicherheitsüberlegungen

Der HTTP-Transport validiert Origin-Header, um DNS-Rebinding-Angriffe zu verhindern
Standardmäßig bindet der HTTP-Transport nur an localhost (127.0.0.1).
Wenn Sie anderen Hosts Zugriff gewähren, sollten Sie zusätzliche Authentifizierungsmaßnahmen in Erwägung ziehen.

Debuggen

So zeigen Sie Debug-Protokolle an:

Bei Verwendung des Stdio-Transports mit Claude Desktop:
- Protokolle erscheinen in den Claude Desktop-Protokollen

Bei Verwendung des HTTP-Transports:

npx @ivotoby/openapi-mcp-server --transport http 2>debug.log

Für Entwickler

Entwicklungstools

npm run build – Erstellt die TypeScript-Quelle
npm run clean – Entfernt Build-Artefakte
npm run typecheck – Führt die TypeScript-Typprüfung aus
npm run lint – Führt ESLint aus
npm run dev – Überwacht Quelldateien und erstellt sie bei Änderungen neu
npm run inspect-watch – Führt den Inspektor mit automatischem Neuladen bei Änderungen aus

Entwicklungs-Workflow

Klonen Sie das Repository
Abhängigkeiten installieren: npm install
Starten Sie die Entwicklungsumgebung: npm run inspect-watch
Nehmen Sie Änderungen an den TypeScript-Dateien in src/
Der Server wird automatisch neu erstellt und neu gestartet

Beitragen

Forken Sie das Repository
Erstellen eines Feature-Zweigs
Nehmen Sie Ihre Änderungen vor
Führen Sie Tests und Lint-Tests aus: npm run typecheck && npm run lint
Senden einer Pull-Anfrage

Lizenz

MIT

OpenAPI MCP Server