Home
Status: Production/Stable
🤖 Can't find what you're looking for? Try our AI-Powered Wiki Search — Ask questions in natural language and get instant answers with source attribution.
The db-mcp SQLite MCP Server enables AI assistants (AntiGravity, Claude, Cursor, etc.) to interact with SQLite databases through the Model Context Protocol. It features 181 native / 154 WASM specialized tools, dual SQLite backends (WASM and Native), Code Mode for token efficiency, deterministic error handling, dual HTTP transport (Streamable HTTP + legacy SSE), OAuth 2.1 authentication, flexible tool filtering, audit logging with DDL backup snapshots, and support for SQLite extensions including FTS5, SpatiaLite, and CSV virtual tables.
- Quick Start — Installation, configuration, and first queries
- HTTP Transport — Streamable HTTP and legacy SSE endpoints for remote access
- Tool Filtering — Stay within AI IDE tool limits with shortcuts and group filters
- Code Mode — 70–90% token reduction via sandboxed JavaScript execution
- Tool Reference — Complete reference of all tools organized by group
- Extensions — Built-in and loadable SQLite extensions (FTS5, SpatiaLite, CSV)
- Resources & Prompts — MCP resources and AI-powered prompts
- OAuth & Security — OAuth 2.1, scopes, supply chain security
- Audit Trail — JSONL audit logging and pre-mutation DDL snapshots
- Troubleshooting — Common issues and solutions
The codebase is organized into modular components under src/:
-
adapters/— SQLite specific logic, implementing both Native (better-sqlite3) and WASM (sql.js) backends, plus prompt and resource handlers. -
audit/— Audit types and constants. -
auth/— OAuth 2.1 implementation and granular scope enforcement. -
cli.ts— CLI argument parsing, server bootstrap, and entry point. -
codemode/— Code Mode API constants and V8 isolate sandbox runtime. -
constants/— System-wide configurations and limits. -
filtering/— Tool filtering logic, dynamic group selection, and configuration. -
observability/— JSONL audit logging, pre-mutation DDL snapshots, and Prometheus metrics. -
server/— Core MCP server implementation, tool registration, and resource subscription management. -
transports/— HTTP (Streamable + SSE) and standard Stdio transport layers. -
types/— Core type definitions. -
utils/— Core utilities including cache management. -
index.ts— Package exports and entry point. -
version.ts— Package version.
| Feature | Description |
|---|---|
| Code Mode (V8 Isolate) | Massive Token Savings: Execute complex, multi-step operations inside a secure V8 isolate with process-level isolation and hard timeouts. Stop burning tokens on back-and-forth tool calls — reduce AI overhead by 70–90%. |
| Deterministic Error Handling | No more cryptic SQLite error codes. Every tool returns structured {success, error, code, category, suggestion, recoverable} responses with actionable remediation so agents recover without guessing. |
| 181 Token-Optimized Tools | The most comprehensive SQLite MCP server available. Every response includes _meta.tokenEstimate and tools support compact, nodesOnly, maxOutliers parameters — letting agents control payload size. |
| Dual SQLite Backends | WASM (sql.js) for zero-compilation portability, Native (better-sqlite3) for full features including transactions, window functions, and SpatiaLite GIS. |
| OAuth 2.1 + Granular Control | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (full, read, write, admin), and Keycloak integration. |
| Audit Trails & DDL Snapshots | Track what AI is doing with JSONL logs, automatically snapshot schemas before destructive operations, and review diffs before restoring. |
| Observability & Metrics | Expose Prometheus metrics at /metrics and persist a structured system.db sidecar for telemetry across server restarts. |
| Resources & Prompts | Agents automatically read real-time schema, health, and configuration metadata. Built-in prompt workflows guide schema exploration, query building, optimization, and migration. |
| Smart Tool Filtering | 10 tool groups + 7 shortcuts let you stay within IDE limits while exposing exactly what you need. Code Mode provides access to all tools through a single endpoint. |
| Enterprise Infrastructure | SQL injection protection, sandboxed code execution, CORS deny-all default, fail-closed scope enforcement, 7 security headers, rate limiting, slowloris timeouts, non-root Docker, and build provenance. |
| Feature | WASM (sql.js) | Native (better-sqlite3) |
|---|---|---|
| Transactions | ❌ | ✅ 8 tools |
| Window Functions | ❌ | ✅ 6 tools |
| SpatiaLite GIS | ❌ | ✅ 7 tools |
| FTS5 | ❌ | ✅ 5 tools |
| Cross-platform | ✅ Pure JavaScript | Compiled natively |
| Performance | 🚀 High-performance, concurrent |
Backend Choice: Use
--sqlite-nativefor full features (transactions, window functions, SpatiaLite). Use--sqlitefor WASM mode (zero native dependencies, cross-platform). See Quick Start for configuration.
| Group | WASM | Native | Description |
|---|---|---|---|
core |
25 | 25 | Basic CRUD, schema, tables |
json |
25 | 25 | JSON/JSONB operations, analysis |
text |
15 | 20 | Text processing + FTS5 + advanced search |
stats |
17 | 23 | Descriptive, inference, window functions |
vector |
11 | 11 | Vector storage, similarity search |
admin |
30 | 31 | DB maintenance, backup, virtual tables |
transactions |
0 | 8 | Commit, rollback, savepoints (Native only) |
geo |
4 | 11 | Geospatial + SpatiaLite (Native only) |
introspection |
10 | 10 | Schema mapping, FK graph, analysis |
migration |
6 | 6 | Schema migration tracking (opt-in) |
+4 built-in tools (
server_info,server_health,list_adapters,sqlite_execute_code) are injected into every group. See Tool Reference for the complete inventory.
AI IDEs have tool limits. Use Code Mode to bypass limits entirely:
# Recommended (access all tools via sandbox)
--tool-filter codemode
# Combine specific groups
--tool-filter core,json,statsSee Tool Filtering for all customization options.
After cloning the repository:
pnpm install # Install dependencies
pnpm run check # Lint + TypeScript strict-mode
pnpm run bench # Run performance benchmarks
pnpm test # Run full test suiteThe project includes a performance benchmark suite powered by Vitest Bench. Benchmarks cover handler dispatch, identifier sanitization, auth middleware, schema parsing, Code Mode, logging, and more.
pnpm run bench # Standard output
pnpm run bench:verbose # Detailed table output- GitHub Repository — Source code & issues
- Docker Hub — Container images
- npm Package — Node.js distribution
- MCP Registry — Official listing
- 🔍 AI-Powered Wiki Search — Natural language documentation search