LiteScope

Litescope

Let AI agents touch production SQLite — safely. Diagnose before the write, rewind after it. For Cloudflare D1, Turso, and local files.

Website · Roadmap · Sponsor

Ask Claude to change your D1 database — and undo it if it's wrong. Every write is dry-run by default with the exact blast radius, and one call away from revert.

Free and open source (AGPL-3.0) — every command, every fleet operation, self-hostable, no license key. The only paid thing is the hosted dashboard we run for you.

---

Why a tool for SQLite?

"It's just a file — what's there to operate?"

That was true when SQLite was a local dev toy. It isn't anymore. D1, Turso, LiteFS, and Litestream put SQLite in production at fleet scale — thousands of databases, one per tenant. But the tooling never caught up:

• `sqlite3` assumes one database. Production assumes thousands. There's no pg_stat, no APM, no standard way to see *from the outside* why a database is locked, why WAL is bloating, or which tenant went silent.
• Embedded means unobservable. The very thing that makes SQLite great — no server — is what leaves you blind in production.
• Agents now write to your data. No SQLite tool was built assuming an AI would run the migration. Litescope was.

Postgres has a mature tool for every problem. SQLite has none — so Litescope is one binary for the whole job: fleet observability, file-level superpowers (bisect / rewind / salvage), lock & WAL diagnostics, and a safe interface for agents. Things a generic DB client structurally can't do.

---

MCP — Give Claude direct access to your D1

Claude Code — install the plugin, which brings the MCP server plus five skills (lock doctor, safe writes, migration review, fleet sweep, corruption recovery) that teach the agent how to use it when something is wrong:

/plugin marketplace add croc100/Litescope

/plugin install litescope@litescope

Or just the MCP server, one line (read-only):

claude mcp add litescope -- litescope mcp

With writes + D1 (Litescope still dry-runs every write and captures a rewind point before applying):

claude mcp add litescope \

-e CLOUDFLARE_API_TOKEN=your-token \ -e CLOUDFLARE_ACCOUNT_ID=your-account-id \ -- litescope mcp --allow-writes

Cursor — one-click: ➕ Add litescope to Cursor (installs read-only; add --allow-writes and the Cloudflare env vars in mcp.json to enable writes).

Claude Desktop / Windsurf / any MCP client — add to the config file directly:

{

"mcpServers": { "litescope": { "command": "litescope", "args": ["mcp", "--allow-writes"], "env": { "CLOUDFLARE_API_TOKEN": "your-token", "CLOUDFLARE_ACCOUNT_ID": "your-account-id" } } } }

Also listed in the MCP Registry as io.github.croc100/litescope.

Then ask Claude things like:

"List my D1 databases"

"Show me the schema of the users table in d1://abc-123" "Delete every inactive user from d1://prod-db-id" ← dry-run first: shows the exact blast radius before you approve the write "Undo that — put it back the way it was" ← one-call revert via the rewind_token from the write "The deploy at 2pm broke something — rewind prod to 1:45pm" "Diff my local dev.db against d1://prod-db-id and show me the migration SQL"

Read-only tools (always available)

litescope_query enforces token budgeting — max_rows cap + columns projection + truncation reporting — so a large table never blows the agent's context window.

Write tools (--allow-writes)

Write tools are off unless you start the server with --allow-writes, every write is dry-run by default, and no write commits without an auto-captured undo point. See the security model for the full boundary — what each layer protects against, and what it doesn't.

Prompts & Resources

Beyond tools, the MCP server exposes prompts — canned workflows like diagnose_locked_database, review_migration, safe_optimize, and health_checkup that chain the tools above into a safe plan — and resources: a database's schema, data dictionary, live health, and live lock diagnosis — readable by the agent without spending a tool call, and subscribable for push updates whenever the underlying file changes. Bind one with litescope mcp ./app.db, or address any source via litescope://schema/{source}, litescope://dictionary/{source}, litescope://health/{source}, and litescope://locks/{source}.

The server implements MCP 2026-07-28, the stateless revision: server/discover, per-request protocol metadata, resultType, caching hints (ttlMs / cacheScope), and subscriptions/listen streams — alongside tool annotations (read-only / destructive hints), structured output (structuredContent + outputSchema) and argument completion. It is dual-era: a client that still opens with the initialize handshake is served MCP 2025-06-18 unchanged, so older MCP clients keep working.

Interactive views (MCP Apps)

Four tools answer with an interactive panel rendered inside the conversation, via the MCP Apps extension (io.modelcontextprotocol/ui):

The views are single self-contained documents compiled into the binary. They load nothing from the network, so the host's strictest CSP applies and a database's contents cannot leave the iframe. They never write, either: a button that would apply or undo a write hands the request back to the conversation, because a click inside an embedded panel is not the user approving a production write. A host without the extension gets the same results as text.

Remote / hosted (Streamable HTTP)

By default litescope mcp speaks stdio. For a hosted, remote, or multi-client setup, serve over the Streamable HTTP transport instead:

litescope mcp --http :7577 --http-token "$LITESCOPE_MCP_TOKEN"

POST a JSON-RPC message to the endpoint (/mcp by default). Modern clients are served statelessly — no session — with each request carrying its own protocol metadata and the standard MCP-Protocol-Version / Mcp-Method / Mcp-Name headers, and change notifications arriving on a subscriptions/listen response stream. Handshake-era clients still get a session via the Mcp-Session-Id header and a GET SSE stream.

Before exposing it publicly, lock it down: --http-token (or the LITESCOPE_MCP_TOKEN env var) requires Authorization: Bearer on every request, and --http-origin allowlists browser Origins (localhost is always allowed) for DNS-rebinding protection. Without a token the endpoint is open and the server prints a warning.

---

D1 — CLI operations

Rewind — D1 Time Travel

# Restore to a previous point in time

litescope rewind d1://DB_ID --to "2h ago" litescope rewind d1://DB_ID --to "yesterday" litescope rewind d1://DB_ID --to "2024-01-15T10:30:00Z"

List available restore points (30-day window + migration timestamps)

litescope rewind list d1://DB_ID

Pull / Push — sync between D1 and local SQLite

# Download D1 → local (for inspection, backup, or diffing)

litescope d1 pull d1://DB_ID ./snapshot.db

Upload local → D1 (seed a fresh database or restore from snapshot)

litescope d1 push ./seed.db d1://DB_ID litescope d1 push ./seed.db d1://DB_ID --drop-existing

Migrate — schema changes on D1

# Diff local dev schema against live D1 — generate migration SQL

litescope migrate local.db d1://DB_ID

Apply a migration directly to D1

litescope migrate apply d1://DB_ID migration.sql

Bisect — find which commit broke a D1 database

Binary-search D1 Time Travel to pinpoint the exact snapshot where a query started returning wrong results:

litescope bisect d1://DB_ID \

--good "3d ago" \ --bad now \ --check "SELECT COUNT(*) FROM orders WHERE status = 'paid'" \ --expect "gt:0"

Checks gt:0 (greater-than), lt:N, eq:N, or a literal value. Narrows to the snapshot window where the condition first failed, then lets you inspect or rewind.

---

Local SQLite

doctor — one-shot checkup

litescope doctor a