sqlite-ro-mcp

A read-only SQLite MCP server in one auditable Python file.

Most "read-only" SQLite MCP servers are write-capable servers with a switch: an env var, or even a tool argument the model itself can flip. This server takes a different position: the write path does not exist.

Defense in depth

1. No mutating tool is defined. There is nothing to toggle.
2. Every statement is validated - head whitelist (SELECT / WITH / EXPLAIN) plus a write-keyword scan on comment- and literal-stripped SQL, so WITH cte AS (...) INSERT ... and keyword-in-string tricks are caught.
3. Connections are opened mode=ro. Even if a validation bug slipped through, SQLite itself refuses the write.

Layer 3 matters: SQLite accepts statements like WITH ... INSERT, which a naive first-word check happily approves. Validation bugs are a when, not an if - the connection flag is the guarantee, the validator is just the first line. The test suite proves this directly: one test bypasses the validator entirely (calls the connection layer straight) and confirms SQLite itself still refuses the write.

The whole server is a single file of a few hundred lines with one dependency (the official mcp SDK). You can audit the entire attack surface in a few minutes.

Install

pipx install sqlite-ro-mcp        # or: pip install sqlite-ro-mcp

Or run from a checkout: pip install -e .

Use with Claude Code

claude mcp add sqlite-ro -- sqlite-ro-mcp --db sales=path/to/sales.db --db logs=path/to/logs.db

Multiple databases are exposed by named alias allowlist - only the files you name are reachable (no directory scanning).

Tools

tool	description
list_databases	aliases and file paths this server exposes
list_tables(db)	tables and views
describe_table(db, table)	columns, types, nullability, primary key
read_query(db, sql, params?)	single SELECT / WITH / EXPLAIN, ? binding, 500-row cap, 30s timeout

Options

usage: sqlite-ro-mcp [-h] --db [NAME=]PATH [--timeout TIMEOUT] [--instructions INSTRUCTIONS]

Read-only SQLite MCP server

options:
  -h, --help            show this help message and exit
  --db [NAME=]PATH      SQLite file to expose; repeatable
  --timeout TIMEOUT     per-query timeout in seconds (default 30)
  --instructions INSTRUCTIONS
                        override the instructions text advertised to clients

Non-goals

Writes of any kind, remote databases, authentication. If you need a write-capable server, use one that is honest about being one.

Authorship

Built with Claude Code. Requirements, the no-write-path design constraint, and review are by the author; implementation is AI-assisted and covered by the test suite in tests/.

License

MIT