baselinker-mcp

Ein MCP-Server, der die gesamte BaseLinker-API — Bestellungen, Rechnungen, Retouren, Kurierdienste, CRM, Lager, Produkte — einem LLM-Client wie Claude Code, Claude Desktop oder Cursor zur Verfügung stellt.

• Vollständig. Alle 179 dokumentierten API-Methoden, keine davon nur als Stub.

• Nur lesend, bis du etwas anderes bestimmst. Die 92 Schreibmethoden bleiben unsichtbar, solange du dich nicht anmeldest; bei deaktiviertem Schreibzugriff meldet jedes Tool readOnlyHint: true.

• Lokal oder remote. stdio für einen Client auf deinem Rechner oder Streamable HTTP mit OAuth 2.1 (Keycloak) für einen gemeinsamen Endpunkt im Internet.

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

Inhalt

• Schnellstart

• Client verbinden

• Tools

• Schreibmethoden

• Wissenswertes Verhalten

• Remote-Bereitstellung (HTTP + OAuth)

• Konfigurationsreferenz

• Fehlerbehebung

• Entwicklung

Related MCP server: TextQL MCP Server

Schnellstart

Voraussetzungen: Node.js 20 oder neuer und ein BaseLinker-API-Token aus dem BaseLinker-Panel unter Konto & Sonstiges → Mein Konto → API.

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

Das Token kann auch direkt aus der Umgebung stammen, was Vorrang vor .env hat. .env wird aus dem Paketstammverzeichnis gelesen, sodass der Server unabhängig davon, aus welchem Verzeichnis dein MCP-Client ihn startet, korrekt startet.

Client verbinden

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop, Cursor oder eine beliebige mcpServers-Konfiguration

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

Für einen gemeinsamen Endpunkt, der von claude.ai aus erreichbar ist, siehe Remote-Bereitstellung.

Tools

179 einzelne Tools würden den Kontext eines Modells und seine Fähigkeit, zwischen ihnen zu wählen, überlasten. Deshalb sind die Methoden so gruppiert, wie BaseLinker sie selbst gruppiert: zehn Tools, eines pro API-Kategorie. Jedes akzeptiert einen method-Namen und ein parameters-Objekt, und die Beschreibung jedes Tools listet die akzeptierten Methoden samt Parametern und Paginierungshinweisen auf.

Die Zahlen unten sind read + write; Schreibmethoden erscheinen nur, wenn BASELINKER_ALLOW_WRITES=true ist.

Parameter werden pro Methode gegen ein Zod-Schema validiert, bevor etwas gesendet wird. Ein fehlerhafter Aufruf führt also zu einem lesbaren Fehler statt zu einem BaseLinker-Fehlercode. Unbekannte Schlüssel werden unverändert weitergeleitet — BaseLinker fügt Parameter ohne Vorwarnung hinzu, und der Server bricht nicht ab, wenn das passiert.

Schreibmethoden

Standardmäßig deaktiviert. Zum Aktivieren:

BASELINKER_ALLOW_WRITES=true

Solange sie deaktiviert sind, werden Schreibmethoden weder im method-Enum eines Tools aufgeführt noch sind sie aufrufbar. Durch das Aktivieren werden alle 92 auf einmal eingeschaltet — Erstellen, Aktualisieren und Löschen von Bestellungen, Produkten, Beständen, Preisen, Rechnungen, Sendungen, Retouren und Lagerbelegen. Einige davon löschen Datensätze; einige lösen echte Kuriersendungen aus, die echtes Geld kosten. Es gibt keine Freischaltung pro Methode. Aktiviere den Schreibzugriff also nur für einen Client, dem du vertraust, und erwäge, für alles andere eine zweite schreibgeschützte Instanz zu betreiben.

Wissenswertes Verhalten

Ratenbegrenzung. BaseLinker erlaubt 100 Anfragen pro Minute. Ein clientseitiger Sliding-Window-Limiter setzt das durch — überzählige Aufrufe warten, anstatt zu scheitern.

Paginierung. Listenantworten sind begrenzt (in der Regel 100 Einträge für Bestellungen, Rechnungen und Retouren; 1000 für Katalogprodukte). Die Beschreibung jeder Methode enthält den entsprechenden Hinweis, z. B. erwartet getOrders, dass date_confirmed_from auf date_confirmed der zuletzt zurückgegebenen Bestellung plus eine Sekunde gesetzt wird, während getInventoryProductsList eine bei 1 beginnende page erwartet.

Dateidownloads. getLabel, getProtocol, getCourierDocument, getInvoiceFile, getInventoryDocumentFile und getInventoryFulfillmentDeliveryLabels geben die Datei als eingebettete MCP-Ressource mit echtem MIME-Typ zurück. Übergib den zusätzlichen Parameter save_to_path — wird lokal behandelt, nie an BaseLinker gesendet —, um sie stattdessen dekodiert auf der Festplatte zu speichern und { saved_to, extension, bytes } zurückzubekommen. Das ergibt nur über stdio Sinn, wo der Server auf deinem eigenen Rechner läuft; über HTTP wird es mit einem erklärenden Fehler abgelehnt.

Remote-Bereitstellung (HTTP + OAuth)

Mit --transport http spricht der Server Streamable HTTP und fungiert als OAuth-2.0-Ressourcenserver (RFC 9728): Er veröffentlicht Metadaten für geschützte Ressourcen, beantwortet nicht authentifizierte Aufrufe mit 401 plus einer WWW-Authenticate-Herausforderung und prüft jedes Zugriffstoken als RS256-JWT gegen die JWKS einer Keycloak-Realm. Clients entdecken die Realm über diese Metadaten und registrieren sich über die dynamische Client-Registrierung, sodass auf keiner Seite eine Client-ID oder ein Geheimnis konfiguriert ist.

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

Der HTTP-Transport weigert sich, ohne eine Auth-Realm zu starten, es sei denn, du entscheidest dich ausdrücklich mit BASELINKER_MCP_AUTH_DISABLED=true dagegen. Das ist beabsichtigt: Bei aktiviertem Schreibzugriff übergibt ein nicht authentifizierter Endpunkt dein BaseLinker-Konto dem Internet.

deploy/ enthält die vollständige Anleitung — Keycloak-Realm-Einrichtung, einen gehärteten Compose-Dienst mit Traefik-Labels, Reverse-Proxy-Ausschnitte für Caddy und nginx, Verifikationsbefehle und ein Bedrohungsmodell. Die Kurzfassung:

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

Dann einen Client darauf ausrichten:

claude mcp add --transport http baselinker https://mcp.example.com/mcp

In claude.ai sind es Einstellungen → Konnektoren → Benutzerdefinierten Konnektor hinzufügen, URL https://mcp.example.com/mcp, wobei Client-ID und Client-Geheimnis leer bleiben.

Eines sollte klar sein, bevor du es bereitstellst: Das BaseLinker-Token wird geteilt. Jeder, der sich in der Realm anmelden kann, arbeitet mit demselben BaseLinker-Konto. Weitere Grenzen findest du in SECURITY.md.

Konfigurationsreferenz

Alles ist eine Umgebungsvariable; .env im Paketstammverzeichnis wird automatisch geladen.

Immer

Transport

CLI-Flags haben Vorrang vor diesen.

OAuth — erforderlich, wenn der Transport http ist

Listen akzeptieren Kommas oder Leerzeichen.

Fehlerbehebung

Weitere OAuth-spezifische Fälle findest du in deploy/README.md.

Entwicklung

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md beschreibt, wie die Tool-Registry aufgebaut ist und worauf beim Hinzufügen einer Methode zu achten ist.

Lizenz

MIT. Nicht mit BaseLinker verbunden oder von BaseLinker unterstützt.