MCP-Server shop-db

Read-only MCP-Server (stdio-Transport), der einem KI-Agenten Zugriff auf die SQLite-Datenbank des Online-Shops shop.db gibt: Kunden, Produkte, Bestellungen und Bestellpositionen.

Basiert auf dem offiziellen MCP Python SDK (v2).

Entwicklungsmetadaten

Das Projekt wurde vollständig von einem KI-Coding-Agenten (Claude Code, Modell Fable 5) gemäß der Spezifikation SPEC.md erzeugt.

Related MCP server: db-mcp

Werkzeuge (Tools)

Sicherheit

Die Datenbank kann über diesen Server nicht verändert werden. Drei unabhängige Schutzebenen:

1. Abfragevalidierung – alles, was kein einzelnes SELECT/WITH ist (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, PRAGMA, ATTACH, mehrere Anweisungen hintereinander, ein in einem Kommentar verstecktes Schreiben), wird mit einer klaren Meldung abgelehnt, noch bevor es ausgeführt wird.

2. Read-only-Verbindung – Die Datei wird über einen SQLite-URI mit mode=ro geöffnet.

3. PRAGMA query_only = ON für jede Verbindung.

Selbst ein Schreibversuch, der die Validierung passiert (z. B. WITH ... INSERT), scheitert an der Read-only-Verbindung.

SQL-Fehler werden als kurze, verständliche Meldungen mit Hinweisen dargestellt – ohne Stack-Traces.

Installation

Benötigt wird Python 3.10+.

Mit uv (empfohlen – beim ersten Start wird automatisch alles installiert):

uv sync

Oder mit pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Konfiguration

Der Server sucht die Datenbank in der Datei shop.db neben server.py – die in der Aufgabe bereitgestellte Datenbank ist im Repository enthalten. Um eine andere Datei zu verwenden, setzen Sie die Umgebungsvariable SHOP_DB_PATH:

export SHOP_DB_PATH=/path/to/shop.db

seed_db.py – ein Hilfsprogramm, das eine Demo-Datenbank mit ähnlichem Schema erzeugt (nur für einmalige Daten nötig; shop.db wird davon nicht verändert, sofern nicht ausdrücklich erbetet):

python seed_db.py /tmp/demo.db

Start

Der Server kommuniziert über stdio – er wird vom MCP-Client gestartet, nicht manuell vom Benutzer. So überprüfen Sie, dass er fehlerfrei startet:

uv run python server.py

(Der Server wartet auf MCP-Nachrichten auf stdin; Beenden mit Ctrl+C)

Anbindung an den Agenten

Claude Code

Im Repository liegt .mcp.json, daher wird der Server aus dem Projektverzeichnis automatisch übernommen. Manuelle Anbindung:

claude mcp add shop-db -- uv run --directory /absolute/path/to/sqlite-mcp python server.py

Claude Desktop (oder conflatt drei beliebigen Client mit JSON-Konfiguration)

Hinzufügen zu claude_desktop_config.json (siehe examples/claude_desktop_config.example.json) – bei der Installation mit pip müssen die Abhängigkeiten in dem Interpreter vorhanden sein, der in der Konfiguration angegeben ist:

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/sqlite-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/sqlite-mcp/server.py"]
    }
  }
}

Oder über uv (manuelle Installation nicht benötigt):

{
  "mcpServers": {
    "shop-db": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/sqlite-mcp", "python", "server.py"]
    }
  }
}

Docker

docker build -t shop-db-mcp .

{
  "mcpServers": {
    "shop-db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shop-db-mcp"]
    }
  }
}

Beispiel Fragen, die der Agent beherrscht

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

• Wie viele Kunden kommen aus Deutschland?

• Welches Land hat die meisten Kunden?

• Wer hat als Kunde am meisten Geld ausgegeben?

• Was sind die 5 meistverkauften Produkte?

• Was sind die 3 Produktkategorien mit dem höchsten Umsatz?

• Wie viel Umsatz haben wir im Jahr 2025 erzielt?

• Welcher Kunde hat die meisten bestellungen aufgegeben?

Destruktive Fragen („Alle abgebrochenen Bestellungen löschen“) läuft auf den Server.

Hinweis zu den bereitgestellten Daten: In customers gibt es keine Spalte in Ländern (lokal) / Lage kann nur anhand der Telefoncodes – alle Nummern +7 – oder E-Mail-Domains geschlossen werden) und alle Bestellungen sind von Februar bis August 2026 datiert. Die Schema-Tools geben dem Agenten alles, um das zu erkennen und ehrlich zu beantworten.

Ergebnisse der Prüfung mit realem Agenten

Alle Aufgaben der Spezifikation wurden mit echten headless-Agenten (claude -p "<вопрос>" --mcp-config .mcp.json, Modell Sonnet) durchgeführt, die nur über die drei MCP-Tools des Servers verfügten – ohne Bash und ohne Dateizugriff. Die Antworten wurden mit Referenzergebnissen abgeglichen, die direkt von SQLite berechnet wurden. Ergebnis: 9/9.

Beobachtung aus den Transscripts: den Agenten reichten fast immer list_tables + einen aggregieren SQL-Abfrage aus – die Tabellenbeschreibungen in den Antworten der Tools (inkl. Hinweis auf eine fehlende Länder-Spalte und Umsatzformel) funktionierten wie gewünscht.

Datenbankschema

customers ──< orders ──< order_items >── products

• customers (150 Zeilen) – id, first_name, last_name, email, phone, created_at

• products (50 Zeilen) – id, name, category, price, st_\content, created_at

• orders (1.750 Zeilen) – id, custom_code → customers, order_date, status (new/processing/shipped/completed/cancelled), total_amount

• order_items (1900 Zeilen) – id, order_id → orders, product_id → products, quantity, unit_price

Tests

uv run pytest

36 Tests decken alle drei Tools ab, Pagination, Fehlerbehandlung, Read-only-Garantien (einschließlich Mehrfachanweisungen und einen Schreibvorgang, der mit ein Anwenden kommentiert ist) sowie den Demo-Daten-Generator

Projektstrukur

server.py        # MCP-сервер (3 инструмента, read-only защита)
shop.db          # выданная в задании база данных
SPEC.md          # спецификация, по которой сгенерирован проект
seed_db.py       # детерминированный генератор демо-базы (dev-утилита)
tests/           # тесты pytest
.mcp.json        # конфиг проекта для Claude Code
examples/        # пример конфига для Claude Desktop
Dockerfile       # опциональный запуск в контейнере