Skip to content
Back to search

queryvault-mcp

Read-only SQLite analytics, query-plan advisor, anomaly detection, and PII-redacting MCP server (Python FastMCP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/azarm0--queryvault-mcp/badge.svg)](/listings/azarm0--queryvault-mcp)

HTML

<a href="/listings/azarm0--queryvault-mcp"><img src="/api/listings/azarm0--queryvault-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Local setup (project-local venv)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Run the live showcase

python scripts/demo_showcase.py

Run the test suite

pytest -v

Run as a server

Stdio transport (default):

queryvault-mcp --db demo.db --seed-demo --transport stdio

Streamable HTTP transport:

queryvault-mcp --db demo.db --seed-demo --transport http --host 127.0.0.1 --port 8000

Docker:

docker build -t queryvault-mcp .
docker run --rm -p 8000:8000 queryvault-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines
  1. # QueryVault MCP
  2. Read-only SQLite Model Context Protocol (MCP) server built with FastMCP and Pydantic v2. It exposes database inspection, guarded SQL execution, automatic PII redaction, query plan auditing, and z-score anomaly detection over `stdio` or Streamable HTTP with zero external API keys.
  3. ## Architecture
  4. ```mermaid
  5. flowchart LR
  6. Client["MCP Client (Claude Desktop / Cursor / FastMCP)"] --> Server["QueryVault FastMCP Server"]
  7. Server --> Guard["SQL Guard (comment strip, stacked check, keyword block)"]
  8. Guard --> DB["SQLite URI (?mode=ro + PRAGMA query_only=ON)"]
  9. DB --> Redactor["PII Redaction Engine (column names + email/phone regex)"]
  10. Redactor --> Audit["Bounded Audit Log (deque maxlen=100)"]
  11. Audit --> Client
  12. ```
  13. ```
  14. MCP Client (stdio / Streamable HTTP)
  15. |
  16. v
  17. +---------------------------------------------------+
  18. | QueryVault FastMCP Server |
  19. | - 5 Tools (list, describe, query, explain, z) |
  20. | - 3 Resources (schema, table sample, audit log) |
  21. | - 2 Prompts (revenue drop, query performance) |
  22. +---------------------------------------------------+
  23. |
  24. v
  25. +---------------------------------------------------+
  26. | Security & Guardrails Layer |
  27. | 1. Comment stripper (-- and /* */) |
  28. | 2. Stacked statement rejector (;) |
  29. | 3. Read-only prefix + blocked keyword filter |
  30. | 4. Identifier allowlist against sqlite_master |
  31. | 5. PII redactor (columns + inline regex) |
  32. +---------------------------------------------------+
  33. |
  34. v
  35. SQLite (?mode=ro, PRAGMA query_only=ON, timeout=5s)
  36. ```
  37. ## MCP Primitives
  38. ### Tools (5)
  39. - `list_tables`: Lists tables, row counts, indexes, and detected PII columns.
  40. - `describe_table(table_name)`: Returns column types, nullability, PK/FK constraints, distinct counts, and PII flags.
  41. - `run_readonly_query(sql, limit=50, redact_pii=True)`: Executes a single guarded `SELECT` or `WITH ... SELECT` statement with execution timing (`elapsed_ms`), row-cap enforcement, and PII redaction.
  42. - `explain_query_plan(sql)`: Runs `EXPLAIN QUERY PLAN`, flags full table `SCAN` steps, and generates `CREATE INDEX` recommendations.
  43. - `detect_anomalies(table_name, column_name, z_threshold=2.0)`: Computes mean, sample standard deviation, and z-score outliers on a validated numeric column.
  44. ### Resources (3)
  45. - `db://schema`: Full JSON schema, index map, PII column inventory, and server limits.
  46. - `db://tables/{table_name}/sample`: PII-redacted 5-row sample of a validated table.
  47. - `db://audit/recent`: Recent in-memory audit log entries (newest first).
  48. ### Prompts (2)
  49. - `investigate_revenue_drop`: Guided workflow chaining schema inspection, z-score anomaly detection, and grouped root-cause queries.
  50. - `audit_query_performance`: Guided workflow chaining `explain_query_plan`, index review, and `CREATE INDEX` proposals.
  51. ## Security Invariants and Hard Caps
  52. - **SQLite Read-Only Enforcement**: Every connection opens via `file:<path>?mode=ro` (`uri=True`) and immediately executes `PRAGMA query_only = ON`.
  53. - **SQL Statement Guard**: Comments (`--` and `/* */`) are stripped before inspection. Stacked statements (`;` followed by non-whitespace) are rejected. Only single `SELECT`, `WITH ... SELECT`, or `EXPLAIN QUERY PLAN SELECT` statements pass. Blocked keywords (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `CREATE`, `REPLACE`, `TRUNCATE`, `ATTACH`, `DETACH`, `VACUUM`, `REINDEX`, `PRAGMA`, `SAVEPOINT`, `RELEASE`, `ROLLBACK`, `BEGIN`, `COMMIT`, `LOAD_EXTENSION`) are rejected outside string literals.
  54. - **PII Redaction**: Columns matching `email`, `phone`, `mobile`, `ssn`, `api_key`, `token`, `password`, or `secret` are masked automatically. Inline email addresses (`a***@example.com`) and phone numbers (`***-***-1234`) inside free-text columns (such as `notes` or `payload`) are also redacted.
  55. - **Hard Caps**:
  56. - Default query row limit: `50`
  57. - Maximum query row limit: `100` (requests above `100` are clamped to `100` with `truncated=True` when additional rows exist)
  58. - SQLite busy timeout: `5.0` seconds
  59. - In-memory audit log retention: `100` entries (`collections.deque(maxlen=100)`)
  60. ## Quickstart
  61. ### Local setup (project-local venv)
  62. ```powershell
  63. python -m venv .venv
  64. .\.venv\Scripts\Activate.ps1
  65. pip install -e ".[dev]"
  66. ```
  67. ### Run the live showcase
  68. ```powershell
  69. python scripts/demo_showcase.py
  70. ```
  71. ### Run the test suite
  72. ```powershell
  73. pytest -v
  74. ```
  75. ### Run as a server
  76. Stdio transport (default):
  77. ```powershell
  78. queryvault-mcp --db demo.db --seed-demo --transport stdio
  79. ```
  80. Streamable HTTP transport:
  81. ```powershell
  82. queryvault-mcp --db demo.db --seed-demo --transport http --host 127.0.0.1 --port 8000
  83. ```
  84. Docker:
  85. ```powershell
  86. docker build -t queryvault-mcp .
  87. docker run --rm -p 8000:8000 queryvault-mcp
  88. ```
  89. ## Client Configuration
  90. ### Claude Desktop (`claude_desktop_config.json`)
  91. ```json
  92. {
  93. "mcpServers": {
  94. "queryvault": {
  95. "command": "C:/path/to/queryvault-mcp/.venv/Scripts/queryvault-mcp.exe",
  96. "args": [
  97. "--db",
  98. "C:/path/to/queryvault-mcp/demo.db",
  99. "--seed-demo",
  100. "--transport",
  101. "stdio"
  102. ]
  103. }
  104. }
  105. }
  106. ```
  107. ### Cursor (`.cursor/mcp.json`)
  108. ```json
  109. {
  110. "mcpServers": {
  111. "queryvault": {
  112. "url": "http://127.0.0.1:8000/mcp"
  113. }
  114. }
  115. }
  116. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.