db-query

Query SQLite .db files and get structured rows — instead of shelling out to sqlite3 with awkward escaping and re-parsing tabular text. Read-only by default for safety.

query({ db_path: "app.db", sql: "SELECT type, count(*) n FROM events WHERE ts > ? GROUP BY type", params: [cutoff] })
→ { columns: ["type", "n"], row_count: 4, rows: [ { type: "click", n: 812 }, … ] }

Tools

• query(db_path, sql, params?) — structured { columns, rows, row_count, truncated }. Use ? placeholders + params. Writes are blocked unless the server runs with DB_QUERY_WRITE=1.
• tables(db_path) — every table + its columns (name/type).
• schema(db_path, table?) — the CREATE DDL.

db_path can be omitted if the server is started with a DB_QUERY_DB default.

Safety

Read-only by default: only SELECT / EXPLAIN / read PRAGMA / WITH …-select statements run; anything mutating is rejected with a clear message. Set DB_QUERY_WRITE=1 to allow writes. Rows are capped at 1000 (with truncated flagged).

Setup

npm install   # Node 22+ (uses the built-in node:sqlite — no native build)
npm test

claude mcp add db-query -- node /abs/path/db-query/dist/server.js
# CLI: agent-db tables app.db
#      agent-db query app.db "SELECT * FROM users LIMIT 5"

Honest limits

• SQLite only (it's what node:sqlite speaks).
• Read-only is enforced by statement inspection, not a sandbox — robust for the common cases, but DB_QUERY_WRITE=1 is the real boundary if you need writes.
• 1000-row cap per query (use LIMIT/WHERE to scope; truncated tells you).