SQLite Guard MCP
A read-only, security-hardened Model Context Protocol server for inspecting local SQLite databases. It leverages the official MCP Python SDK, SQLite's read-only URI mode, native SQLite authorizer enforcement, bounded query execution, and heuristic masking for sensitive columns and credentials.
Security note: This is defense in depth, not an operating-system sandbox. The process can read any database file its operating-system account can access and that the operator configures. Column-name masking is heuristic and is not a substitute for database-level access controls. See SECURITY.md.
Features
- Standard MCP transports (
stdio,sse, andstreamable-http) through the official MCP Python SDK. - Read-only
SELECT,WITH, andVALUESqueries with bound parameters. - Built-in schema inspection: separate tools for listing tables, describing schemas, and explaining query plans.
- MCP Resource support:
schema://summaryprovides zero-turn inspection of tables and schemas. - Rich parameter schemas with docstrings and descriptions for LLM agents.
- SQLite authorizer strictly denies write operations, database attachments, dangerous functions (
load_extension,readfile,writefile,fsdir,eval, etc.), and unapproved PRAGMAs. - Sensitive credential columns (
password,api_key,access_key,secret,private_key,credit_card, etc.) are masked asNULLat SQLite's authorizer boundary. - Usage token metrics (
prompt_tokens,completion_tokens,total_tokens, etc.) are explicitly preserved. - Hard resource bounds: query timeout, SQLite VM-step budget, row cap, column cap, text cell length cap, and total response byte size cap.
- BLOB values are returned as bounded Base64 previews rather than raw byte dumps.
Requirements
- Python 3.11 or newer.
- The package installs the official
mcpSDK 2.x andpydanticautomatically. - An existing SQLite database file readable by the current operating-system account.
Install from source
git clone https://github.com/AtharvaSiddhawar/sqlite-guard-mcp.git
cd sqlite-guard-mcp
python -m pip install .
For development:
python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest --cov --cov-report=term-missing
python -m build
Run
sqlite-guard-mcp --db "/absolute/path/to/database.sqlite"
Optional limits and transport flags:
sqlite-guard-mcp --db "/path/to/database.sqlite" --max-rows 250 --timeout 2.0 --max-vm-steps 250000 --transport stdio
You can also set SQLITE_GUARD_DB and omit --db. Check version with sqlite-guard-mcp --version.
MCP client configuration
Example Claude Desktop-style configuration (adjust the Python executable and database path for your computer):
{
"mcpServers": {
"sqlite-guard": {
"command": "sqlite-guard-mcp",
"args": ["--db", "/absolute/path/to/database.sqlite"]
}
}
}
If the executable is not on the client's PATH, use the full path to the virtual environment's sqlite-guard-mcp executable.
Tools
| Tool | Purpose |
|---|---|
read_query(sql, params?) |
Run one read-only SELECT, WITH, or VALUES query with bound parameters. |
list_database_tables() |
List user-defined tables and views. |
describe_database_table(table_name) |
Inspect columns, types, primary keys, indexes, foreign keys, and masking metadata. |
explain_read_query(sql, params?) |
Run EXPLAIN QUERY PLAN for a read-only query. |
params accepts a JSON object for named parameters or an array for positional parameters. Example: {"sql":"SELECT name FROM people WHERE id = ?","params":[7]}.
Resources
| Resource URI | Purpose |
|---|---|
schema://summary |
Provides a complete JSON summary of all tables, views, and columns without requiring multiple tool calls. |
Masking behavior
The authorizer masks common credential and secret columns such as password, passwd, pwd, secret, api_key, access_key, auth_key, private_key, client_secret, ssn, social_security, credit_card, card_number, cvv, bank_account, and session tokens.
Common usage metrics such as prompt_tokens, completion_tokens, input_tokens, output_tokens, and total_tokens are intentionally not masked. These rules are name-based heuristics: review your schema and do not rely on them as an absolute data-loss-prevention system.
Limits and behavior
SELECT,WITH, andVALUESqueries are accepted; mutations and write CTEs are rejected.explain_read_queryaccepts read-only queries and prependsEXPLAIN QUERY PLANsafely.- The default row limit is 250, with a hard limit of 1,000.
- Query execution is strictly bounded by wall-clock timeout and SQLite VM-step budget.
- Text cells (4 KB max), BLOB previews (4 KB max), columns (100 max), and total serialized response size (1 MB max) are capped.
- Multiple SQL statements in one call are rejected by SQLite's single-statement execution boundary.
Skill instructions
The agent-facing usage guide is in SKILL.md.
License
MIT. See LICENSE.
Metadata
Release files for sqlite-guard-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sqlite_guard_mcp-0.2.0.tar.gz | 17.8 kB | With provenance | Details for sqlite_guard_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sqlite_guard_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for sqlite_guard_mcp-0.2.0-py3-none-any.whl |
Total release size: 30.9 kB
Release files / sqlite_guard_mcp-0.2.0.tar.gz
| Download URL | sqlite_guard_mcp-0.2.0.tar.gz |
|---|---|
| Size | 17.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd70623c756d87ad204f25cb0434f883e70912f24304e80a18ba569f36f95d3c
|
|
BLAKE2b-256 checksum How to use checksums |
75e36486ff97273b99f8abf7388b15aff91dc33a1d88830984b181190bc304ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / sqlite_guard_mcp-0.2.0-py3-none-any.whl
| Download URL | sqlite_guard_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 13.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
21d6fd5e053936c96dd253b46d8f0da894bd41b9554d3d1b5016cec90b698772
|
|
BLAKE2b-256 checksum How to use checksums |
96e7f7c8389a8cb91695aa9f07a273e71f8ca6379dd452a8f59ee11d1dfcbb73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for sqlite-guard-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sqlite_guard_mcp-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.