Shop Analytics MCP

MCP-Server in TypeScript für die sichere Analyse der SQLite-Datenbank eines Online-Shops. Funktioniert nur über stdio und stellt sechs spezialisierte Tools bereit; beliebiges SQL wird nicht akzeptiert.

Anforderungen

• Node.js 24.10+;

• npm;

• sqlite3-CLI nur zur erneuten Anwendung der Migration.

Related MCP server: mcp-analytics-server

Installation und Start

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

SHOP_DB_PATH hat Priorität. Wenn die Variable nicht gesetzt ist, sucht der Server shop.db im aktuellen Arbeitsverzeichnis. Der Pfad zur Datenbank ist nicht im Quellcode fest verdrahtet.

Daten

Im Repository befindet sich eine fertig migrierte shop.db. Sie enthält die Länder der Kunden und Daten für das Jahr 2025. Geldwerte werden als EUR interpretiert und nicht konvertiert.

Um die Migration einmalig auf die ursprüngliche Datenbank anzuwenden:

npm run migrate

Das ursprüngliche Schema befindet sich in database/schema.sql, die deterministische Migration in database/001-add-analytics-data.sql.

Verbindung zum Client

Vorgefertigte Konfigurationsvorlagen befinden sich in config/:

• claude-code.mcp.json;

• codex.mcp.json;

• cursor.mcp.json.

Ersetzen Sie /absolute/path/to/mcp-server in der gewählten Vorlage durch den Pfad zu diesem Projekt. Alle Konfigurationen starten dist/src/index.js über stdio und übergeben den Pfad zu shop.db über SHOP_DB_PATH.

Tools

Finanz- und Produktkennzahlen sowie die Anzahl der Bestellungen schließen cancelled aus. Beträge werden in Feldern mit dem Suffix Eur zurückgegeben. Ranglisten akzeptieren limit von 1 bis 100; Zeiträume verwenden Daten im Format YYYY-MM-DD.

Beispiel

Unten ist zu sehen, wie ein MCP-Client get_database_schema aufruft, um die Tabellen zu beschreiben, und anschließend get_customer_metrics, um die Kunden aus Deutschland zu zählen.

Sicherheit

• SQLite wird mit readOnly: true und PRAGMA query_only = ON geöffnet.

• Der SQLite-Authorizer verbietet Schreibvorgänge, DDL, ATTACH, DETACH und Transaktionen.

• Alle Werte werden als SQL-Parameter gebunden.

• Tools akzeptieren kein SQL, daher kann der Agent keine destruktiven Anweisungen übergeben.

• Validierungsfehler offenbaren weder SQL, absolute Pfade noch Stack-Traces.

Tests

npm test

Die Tests decken die Referenzantworten auf acht Abnahmefragen ab, SQL-Injection im Länderparameter, das Verbot von DELETE, die Unveränderlichkeit einer temporären DB-Kopie per SHA-256 sowie die MCP-Interaktion über stdio.

Abnahmefragen

1. Zeig mir alle verfügbaren Tabellen und erkläre, welche Informationen jede Tabelle enthält.

2. Wie viele Kunden kommen aus Deutschland?

3. Welches Land hat die meisten Kunden?

4. Wer ist der Kunde, der das meiste Geld ausgegeben hat?

5. Was sind die 5 meistverkauften Produkte?

6. Was sind die 3 umsatzstärksten Produktkategorien?

7. Wie viel Umsatz haben wir im Jahr 2025 erzielt?

8. Welcher Kunde hat die meisten Bestellungen aufgegeben?