MCP SQLite 服务器（只读）

一个生产就绪的 Model Context Protocol 服务器，为 AI 代理提供对 SQLite 数据库（shop.db）的安全、只读访问。基于官方 mcp Python SDK 构建，使用 stdio 传输。

功能特性

• 3 个 MCP 工具：list_tables、describe_table、query_database

• 纵深防御式只读安全：SQLite URI 只读模式 + PRAGMA query_only + SQL 验证器 + EXPLAIN 操作码检查

• 查询验证：拒绝 INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/REPLACE/TRUNCATE/ATTACH/DETACH、多语句查询（;）、SQL 注释（--、/* */）以及修改性 PRAGMA——且不会对字符串字面量产生误报

• 分页：默认行数限制（100）、limit/offset 参数、截断输出标志

• 仅 stderr 日志：所有日志/回溯信息输出到 sys.stderr；stdout 专用于 JSON-RPC

• 完整类型注解：mypy --strict 零错误

• TDD：105 个测试，涵盖安全性、数据库层、MCP 工具、8 个基准查询以及 stderr 保护

Related MCP server: sqlite-mcp-server

快速开始

前置条件

• Python 3.10+

• 一个 SQLite 数据库文件（默认：./shop.db）

本地设置

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

配置

复制 .env.example 并设置数据库路径：

cp .env.example .env
# Edit DATABASE_PATH to point to your SQLite file

或者直接设置环境变量：

export DATABASE_PATH=/abs/path/to/shop.db

运行服务器

python -m mcp_server.server

服务器通过 stdin/stdout 使用 MCP stdio 传输进行通信。你不需要直接与它交互——MCP 客户端（例如 Claude Desktop、你的 AI 代理）会连接到它。

MCP 客户端配置

标准 Python

将此配置添加到你的 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "DATABASE_PATH": "/abs/path/to/shop.db"
      }
    }
  }
}

Docker

首先构建镜像：

docker build -t mcp-shop:latest .

然后配置你的 MCP 客户端：

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/abs/path/to/shop.db:/app/shop.db",
        "-e", "DATABASE_PATH=/app/shop.db",
        "mcp-shop:latest"
      ]
    }
  }
}

Docker Compose

docker compose up -d

工具

list_tables

列出数据库中的所有用户表和视图（排除内部的 sqlite_* 表）。

参数：无

返回：

{
  "tables": ["customers", "orders", "order_items", "products"],
  "count": 4
}

describe_table

描述表的模式：列、外键、行数以及 CREATE 语句。

参数：

• table（字符串，必填）：要描述的表名。

返回：

{
  "table": "customers",
  "columns": [
    {"cid": 0, "name": "id", "type": "INTEGER", "notnull": 0, "default": null, "pk": 1},
    {"cid": 1, "name": "first_name", "type": "TEXT", "notnull": 1, "default": null, "pk": 0}
  ],
  "foreign_keys": [],
  "row_count": 150,
  "sql": "CREATE TABLE customers (...)"
}

query_database

执行带分页支持的只读 SQL 查询。

参数：

• sql（字符串，必填）：单条只读 SQL 语句（SELECT、WITH、EXPLAIN 或只读 PRAGMA）。

• limit（整数，可选）：返回的最大行数。默认值：100。最大值：1000。

• offset（整数，可选）：跳过的行数。默认值：0。

返回：

{
  "columns": ["id", "first_name"],
  "rows": [{"id": 1, "first_name": "Alice"}, {"id": 2, "first_name": "Bob"}],
  "row_count": 2,
  "truncated": false,
  "limit": 100,
  "offset": 0
}

当 truncated 为 true 时，表示还有更多行可用——增加 offset 以获取下一页。

安全性

服务器实现了纵深防御以保证只读访问：

第 1 层：SQLite 连接（URI 只读模式）

数据库以 file:<path>?mode=ro 方式打开，这会在 SQLite 引擎层面阻止写入。此外，每个连接都会设置 PRAGMA query_only = ON。

第 2 层：SQL 查询验证器（security.py）

在任何查询到达 SQLite 之前，它都会经过一个多阶段验证器：

1. 字符串字面量剥离：字符串字面量（'...'、"..."）会被替换为占位符，这样数据中的关键字（例如名为 "Deleted Item" 的产品）不会触发误报。

2. 注释检测：SQL 注释（--、/* */）会被拒绝，以防止基于注释的绕过。

3. 多语句拒绝：任何分号（;）都会被拒绝，防止堆叠查询。

4. 关键字分析：第一条实际语句关键字必须是 SELECT、WITH、EXPLAIN 或 PRAGMA。破坏性关键字（INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、REPLACE、TRUNCATE、ATTACH、DETACH、VACUUM 等）会被阻止。

5. PRAGMA 验证：只读 PRAGMA（table_info、database_list 等）被允许。任何带有赋值（=）的 PRAGMA 或位于可变 PRAGMA 黑名单（journal_mode、synchronous、foreign_keys 等）中的 PRAGMA 都会被拒绝。

第 3 层：EXPLAIN 操作码检查

作为最后一道防线，查询会通过 EXPLAIN <query> 经过 SQLite 自身的解析器。生成的操作码流会被检查是否存在写操作码（OpenWrite、Insert、Delete、Create、Drop 等）以及写事务标志。如果发现任何此类操作码，查询将被拒绝。

第 4 层：净化后的错误消息

返回给客户端的所有错误消息都经过净化——文件系统路径和内部细节会被剥离，以防止信息泄露。

测试

测试仅使用临时/内存数据库——绝不使用生产环境的 shop.db。

# Run all tests
python -m pytest

# Run with verbose output
python -m pytest -v

# Run a specific test file
python -m pytest tests/test_security.py

测试覆盖率

静态分析

# Type checking
python -m mypy

# Linting
python -m ruff check src/ tests/

项目结构

.
├── .env.example          # Environment variable template
├── Dockerfile            # Docker containerization
├── docker-compose.yml    # Docker Compose config
├── pyproject.toml        # Package config, deps, tool settings
├── README.md             # This file
├── shop.db               # The SQLite database (not included in tests)
├── src/mcp_server/
│   ├── __init__.py
│   ├── config.py         # Configuration (DATABASE_PATH, limits, URI builder)
│   ├── db.py             # Read-only Database class with introspection + query
│   ├── security.py       # SQL validator (multi-layer defense-in-depth)
│   ├── server.py         # MCP server entrypoint (stdio transport)
│   ├── tools.py          # MCP tool definitions and handlers
│   └── py.typed          # PEP 561 marker
└── tests/
    ├── __init__.py
    ├── test_db.py        # Database layer + benchmark tests
    ├── test_security.py  # Query validator tests
    └── test_server.py    # MCP server/tool tests

基准任务

服务器的工具使 AI 代理能够执行以下分析任务（已通过针对受控夹具数据库的测试验证）：

1. 表发现：list_tables + describe_table——列出所有表并描述模式。

2. 过滤计数：使用 SELECT COUNT(*) FROM customers WHERE country = 'Germany' 进行 query_database。

3. 国家聚合：SELECT country, COUNT(*) ... GROUP BY country ORDER BY ... DESC LIMIT 1。

4. 客户生命周期价值：连接 customers + orders，SUM(total_amount)，按总额排序。

5. 产品表现：连接 order_items + products，按数量和收入聚合，LIMIT 5。

6. 类别聚合：遍历 order_items → products → category，聚合收入，LIMIT 3。

7. 日期过滤：SUM(total_amount) WHERE substr(order_date,1,4) = '2025'。

8. 订单聚合：连接 customers + orders，COUNT(o.id)，按数量排序。

配置

许可证

本项目按原样提供，仅用于演示目的。