Read-only MCP server for a store

Python MCP server over stdio for an existing SQLite database of an online store (data/shop.db). The database file is opened read-only; modifying SQL is rejected and not executed.

Installation

Python 3.11+:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Related MCP server: sqlite-mcp-local

Running

From the project root (default database path is ./data/shop.db):

python -m shop_mcp
# или
shop-mcp

Another database path:

SHOP_DB_PATH=~/my/test-mcp-db/data/shop.db python -m shop_mcp

The process communicates via MCP through stdin/stdout. Don't enter commands into this terminal until an MCP client is connected to it.

MCP config in Cursor

Add an mcpServers entry (Cursor Settings → MCP, or .cursor/mcp.json in the project). The transport is stdio.

In the examples, the path ~/my/test-mcp-db is this repository. The server expands SHOP_DB_PATH itself (~ → home directory). If Cursor doesn't expand ~ in command / cwd, specify /Users/<you>/my/test-mcp-db/... there.

Locally (venv)

{
  "mcpServers": {
    "shop": {
      "command": "~/my/test-mcp-db/.venv/bin/python",
      "args": ["-m", "shop_mcp"],
      "cwd": "~/my/test-mcp-db",
      "env": {
        "SHOP_DB_PATH": "~/my/test-mcp-db/data/shop.db"
      }
    }
  }
}

If a console script is more convenient after pip install -e .:

{
  "mcpServers": {
    "shop": {
      "command": "~/my/test-mcp-db/.venv/bin/shop-mcp",
      "cwd": "~/my/test-mcp-db",
      "env": {
        "SHOP_DB_PATH": "~/my/test-mcp-db/data/shop.db"
      }
    }
  }
}

Docker

Build the image once:

docker build -t shop-mcp .

{
  "mcpServers": {
    "shop": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/my/test-mcp-db/data/shop.db:/data/shop.db:ro",
        "-e",
        "SHOP_DB_PATH=/data/shop.db",
        "shop-mcp"
      ]
    }
  }
}

The -i flag is required to keep stdio connected. Mount only shop.db; the container must not overwrite the file on the host.

Tools

Amounts, quantities, and revenue are calculated as order_items.quantity * order_items.unit_price; orders with the cancelled status are excluded. The calendar year is taken from strftime('%Y', orders.order_date).

Security

• SQLite URI file:<abs>?mode=ro

• Comments are stripped; query chains (SELECT 1; DELETE ...) are rejected

• INSERT / UPDATE / DELETE / DROP / ALTER / CREATE / ATTACH / PRAGMA / … → explicit "not allowed" error

• SQLite syntax errors and unknown columns are returned in a structured way; the process doesn't terminate

Notes on evaluation

• The customers table has no country column. That is visible through describe_table; don't invent geography. SELECT country FROM customers will return an SQLite error.

• Order dates in the current dump are from 2026. Revenue for 2025 may be 0. That's a correct result, not a broken filter.

Tests

pytest

The tests copy data/shop.db to a temporary file and verify that the copy's hash doesn't change after rejected writes.

Example of a processed query