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:

1. Stdio-Transport (Standard): Für die direkte Integration mit KI-Systemen wie Claude Desktop, die MCP-Verbindungen über Standard-Eingabe/Ausgabe verwalten.

2. 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: MCP OpenAPI Server

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:

1. Suchen oder erstellen Sie Ihre Claude Desktop-Konfigurationsdatei:

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

2. 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"
      }
    }
  }
}

3. 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:

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

2. 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:

1. Bei Verwendung des Stdio-Transports mit Claude Desktop:

   • Protokolle erscheinen in den Claude Desktop-Protokollen

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

1. Klonen Sie das Repository

2. Abhängigkeiten installieren: npm install

3. Starten Sie die Entwicklungsumgebung: npm run inspect-watch

4. Nehmen Sie Änderungen an den TypeScript-Dateien in src/

5. Der Server wird automatisch neu erstellt und neu gestartet

Beitragen

1. Forken Sie das Repository

2. Erstellen eines Feature-Zweigs

3. Nehmen Sie Ihre Änderungen vor

4. Führen Sie Tests und Lint-Tests aus: npm run typecheck && npm run lint

5. Senden einer Pull-Anfrage

Lizenz

MIT