MCP server for an online store database (read-only)

MCP server in Python (mcp SDK) that gives an AI agent safe access to the SQLite database shop.db. Works over stdio, connects to the database itself, does not modify data.

Features

• list_tables — list of tables and row counts.

• describe_table — table schema: columns, types, keys, foreign keys.

• query_database — read-only SQL (SELECT/WITH/VALUES/EXPLAIN) with aggregations, JOINs, pagination, and a row limit.

Safety (read-only)

Triple protection against database modification:

1. The connection is opened in mode=ro — SQLite itself physically blocks writes.

2. Additionally, PRAGMA query_only = ON is enabled.

3. Query validation: INSERT/UPDATE/DELETE/DROP/ALTER/CREATE and other destructive operations are forbidden, and multiple statements per single call are forbidden.

The query "Delete all cancelled orders" will be rejected with a clear error, and the database remains unchanged.

Related MCP server: sqlite-mcp

Installation

cd /path/to/project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

By default, the server looks for shop.db next to mcp_server.py. If the database is in another location, set the path via an environment variable:

export SHOP_DB_PATH=/absolute/path/to/shop.db

Running

python mcp_server.py

The server communicates over stdio, so it is not launched manually, but as a child process of the agent (see below). You can verify that everything is up and running like this:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' | python mcp_server.py

Connecting to the AI agent (Claude Code)

Add the server to the MCP configuration. Example for ~/.claude.json or the project's .mcp.json (see mcp_config.json.example):

{
  "mcpServers": {
    "shop-db": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["/path/to/project/mcp_server.py"],
      "env": {
        "SHOP_DB_PATH": "/path/to/project/shop.db"
      }
    }
  }
}

In Claude Code: /mcp → confirm that the shop-db server is connected. After that, the agent can answer analytical questions about the store data.

Tests

source .venv/bin/activate
python -m pytest tests/ -q

Structure

mcp_server.py            # сам MCP-сервер
shop.db                  # база данных (read-only)
requirements.txt         # зависимости
mcp_config.json.example  # пример подключения к агенту
tests/test_server.py     # автотесты