Skip to main content

SQLite Guard MCP

CI Python License

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, and streamable-http) through the official MCP Python SDK.
  • Read-only SELECT, WITH, and VALUES queries with bound parameters.
  • Built-in schema inspection: separate tools for listing tables, describing schemas, and explaining query plans.
  • MCP Resource support: schema://summary provides 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 as NULL at 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 mcp SDK 2.x and pydantic automatically.
  • 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, and VALUES queries are accepted; mutations and write CTEs are rejected.
  • explain_read_query accepts read-only queries and prepends EXPLAIN QUERY PLAN safely.
  • 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)

Source distribution for sqlite-guard-mcp 0.2.0
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)

Table of built distributions (wheels) for sqlite-guard-mcp 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page