# Db Mcp > Secure Database MCP Server featuring a V8 Isolate Code Mode sandbox that unifies 181+ tools, delivering 70-90% token savings. Built for enterprise with HTTP/SSE transports, OAuth 2.1, dynamic filtering, granular RBAC, audit logging, deterministic error handling, Prometheus metrics, and encryption at rest for maximum observability and safety. - **Type:** MCP server - **Install:** `agentstack add mcp-neverinfamous-db-mcp` - **Verified:** Pending review - **Seller:** [neverinfamous](https://agentstack.voostack.com/s/neverinfamous) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [neverinfamous](https://github.com/neverinfamous) - **Source:** https://github.com/neverinfamous/db-mcp - **Website:** https://search.adamic.tech/ ## Install ```sh agentstack add mcp-neverinfamous-db-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # db-mcp (SQLite MCP Server) **SQLite MCP Server** with 170+ specialized tools, 11 data resources + 11 help resources, and 10 prompts, audit logging with DDL backup snapshots, HTTP/SSE Transport, OAuth 2.1 authentication, tool filtering, granular access control, and structured error handling with categorized, actionable responses. Available in WASM and better-sqlite3 variants. [](https://github.com/neverinfamous/db-mcp) [](https://www.npmjs.com/package/db-mcp) [](https://hub.docker.com/r/writenotenow/db-mcp) [](https://opensource.org/licenses/MIT) [](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/db-mcp) [](SECURITY.md) [](https://github.com/neverinfamous/db-mcp) [](https://github.com/neverinfamous/db-mcp/actions/workflows/e2e.yml) [](https://github.com/neverinfamous/db-mcp) [](https://github.com/neverinfamous/db-mcp) **[Wiki](https://github.com/neverinfamous/db-mcp/wiki)** • **[Changelog](CHANGELOG.md)** --- ## 🎯 What Sets Us Apart | Feature | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **181+ Specialized Tools** | The most comprehensive SQLite MCP server available — core CRUD, JSON/JSONB, FTS5 full-text search, statistical analysis, vector search, geospatial/SpatiaLite, introspection, migration, and admin | | **Deep Observability** | Built-in Prometheus `/metrics` export, real-time `sqlite://metrics` MCP resource, historical persistence to a `SystemDb` sidecar, and a granular `sqlite_audit_search` tool for compliance and investigation | | **Dynamic Configuration** | Full YAML/JSON config file support (`--config`) with precedence rules, plus a `sqlite_server_config` tool for live runtime config updates (e.g., log levels) without server restarts | | **Advanced Query & Search** | O(1) cursor-based keyset pagination, faceted search aggregation, and `sqlite_hybrid_search` orchestrating FTS5 + Vector similarity with Reciprocal Rank Fusion (RRF) in a single tool call | | **AI Index Recommendations** | `sqlite_index_audit` automatically analyzes `EXPLAIN QUERY PLAN` responses to suggest optimized composite and partial indexes based on workload patterns | | **Real-time Subscriptions** | Native `resources/subscribe` support pushing event-driven notifications for `sqlite://schema` DDL changes and periodic `sqlite://health` updates directly to clients | | **22 Resources** | 11 data resources (schema, tables, table_schema, indexes, views, health, meta, audit, metrics, compile_options, pragma) + 11 help resources (`sqlite://help` + per-group reference) — filtered by `--tool-filter` | | **10 AI-Powered Prompts** | Guided workflows for schema exploration, query building, data analysis, optimization, migration, debugging, and hybrid FTS5 + vector search | | **Code Mode** | **Massive Token Savings:** Execute complex, multi-step operations inside a **V8 isolate sandbox** with process-level isolation and hard timeouts. Instead of spending thousands of tokens on back-and-forth tool calls, Code Mode exposes all 180+ capabilities locally, reducing token overhead by 70–90% and supercharging AI agent reasoning | | **Token-Optimized Payloads** | Every tool response is designed for minimal token footprint with `_meta.tokenEstimate` on every response so agents know their token cost. Tools include `compact`, `nodesOnly`, `maxOutliers`, `minSeverity`, and `maxInvalid` parameters where applicable — letting agents control response size without losing data access | | **Dual SQLite Backends** | WASM (sql.js) for zero-compilation portability, Native (better-sqlite3) for high-performance concurrent execution with full features including transactions, window functions, and SpatiaLite GIS | | **OAuth 2.1 + Access Control** | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`full`, `read`, `write`, `admin`, `db:*`, `table:*:*`), and Keycloak integration | | **Smart Tool Filtering** | 10 tool groups + 7 shortcuts let you stay within IDE limits while exposing exactly what you need | | **HTTP Streaming Transport** | Streamable HTTP (`/mcp`) for modern clients + legacy SSE (`/sse`) for backward compatibility — both protocols supported simultaneously with security headers, rate limiting, health check, and stateless mode for serverless | | **Production-Ready Security** | SQL injection protection (parameterized queries + Unicode-normalized WHERE clause validation), sandboxed code execution (V8 `codeGeneration` restrictions, frozen prototypes, 29 blocked patterns, Proxy nullified, RPC allowlist), CORS deny-all default, fail-closed scope enforcement, JWT claims sanitization, 7 security headers, body size limits, rate limiting with Retry-After, slowloris timeouts, `trustedProxyIps`, opt-in HSTS, non-root Docker, and build provenance | | **Encryption at Rest** | Native SQLCipher support via `--encryption-key` or `DB_ENCRYPTION_KEY`. Dynamically loads `better-sqlite3-multiple-ciphers` and automatically encrypts the sidecar `SystemDb` audit logs to prevent sensitive queries from leaking | | **Strict TypeScript** | 100% type-safe codebase with strict mode, no `any` types, 1911 unit tests + 1136 E2E tests and 90% coverage | | **Deterministic Error Handling** | Every tool returns structured `{success, error, code, category, suggestion, recoverable}` responses — no raw exceptions, no silent failures. Agents get enriched error context with actionable suggestions instead of cryptic SQLite codes | | **MCP 2025-03-26 Compliant** | Full protocol support with tool safety hints (`sensitiveHint`, `readOnlyHint`), resource priorities, and progress notifications | ## 🚀 Quick Start ### Option 1: Docker (Recommended) Pull and run instantly: ```bash docker pull writenotenow/db-mcp:latest ``` Run with volume mount: ```bash docker run -i --rm \ -v $(pwd):/workspace \ writenotenow/db-mcp:latest \ --sqlite-native /workspace/database.db ``` ### Option 2: Node.js Installation Clone the repository: ```bash git clone https://github.com/neverinfamous/db-mcp.git ``` Navigate to directory: ```bash cd db-mcp ``` Install dependencies: ```bash pnpm install ``` Build the project: ```bash pnpm run build ``` Run the server with **Native backend** (better-sqlite3 — full features, requires Node.js native build): ```bash node dist/cli.js --transport stdio --sqlite-native ./database.db ``` Or with **WASM backend** (sql.js — cross-platform, no compilation required): ```bash node dist/cli.js --transport stdio --sqlite ./database.db ``` > **Backend Choice:** Use `--sqlite-native` for full features (181 MCP tools / 170 group tools, transactions, window functions, SpatiaLite). Use `--sqlite` for WASM mode (154 MCP tools / 143 group tools, no native dependencies). ### Verify It Works ```bash node dist/cli.js --transport stdio --sqlite-native :memory: ``` Expected output: ``` [db-mcp] Starting MCP server... [db-mcp] Registered adapter: Native SQLite Adapter (better-sqlite3) (sqlite:default) [db-mcp] Server started successfully ``` Run the test suite: ```bash pnpm run test ``` ### Prerequisites - ✅ Docker installed and running (for Docker method) - ✅ Node.js 24+ (LTS) (for local installation) ## Code Mode: Maximum Efficiency Code Mode (`sqlite_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets. Code executes in a **worker-thread sandbox** — a separate V8 isolate with its own memory space. All `sqlite.*` API calls are forwarded to the main thread via a `MessagePort`-based RPC bridge, where the actual database operations execute. This provides: - **Process-level isolation** — user code runs in a separate V8 instance with enforced heap limits - **Readonly enforcement** — when `readonly: true`, stripped methods throw clear error messages listing available methods via Proxy traps - **Hard timeouts** — worker termination if execution exceeds the configured limit - **V8 code generation restrictions** — `eval()` and `Function()` construction from strings disabled at the V8 engine level via `codeGeneration: { strings: false, wasm: false }` - **RPC allowlist** — host-side validation prevents workers from invoking unauthorized API methods - **Full API access** — all 10 tool groups are available via `sqlite.*` (e.g., `sqlite.core.readQuery()`, `sqlite.json.extract()`) Set `CODEMODE_ISOLATION=vm` with `CODEMODE_ISOLATION_INSECURE=1` to fall back to the in-process `vm` module sandbox if needed. ### ⚡ Code Mode Only (Maximum Token Savings) If you control your own setup, you can run with **only Code Mode enabled** — a single tool that provides access to all 180+ tools' worth of capability through the `sqlite.*` API: ```json { "mcpServers": { "db-mcp-sqlite": { "command": "node", "args": [ "/path/to/db-mcp/dist/cli.js", "--transport", "stdio", "--sqlite-native", "/path/to/database.db", "--tool-filter", "codemode" ] } } } ``` This exposes just `sqlite_execute_code` plus built-in tools. The agent writes JavaScript against the typed `sqlite.*` SDK — composing queries, chaining operations across all 10 tool groups, and returning exactly the data it needs — in one execution. This mirrors the [Code Mode pattern](https://blog.cloudflare.com/code-mode-mcp/) pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist. > [!TIP] > **Maximize Token Savings:** Instruct your AI agent to prefer Code Mode over individual tool calls: > > _"When using db-mcp, prefer `sqlite_execute_code` (Code Mode) for multi-step database operations to minimize token usage."_ --- ## 🎛️ Tool Filtering > [!IMPORTANT] > **AI-enabled IDEs like Cursor have tool limits.** With 180+ tools in the native backend, you must use tool filtering to stay within limits. Use **shortcuts** or specify **groups** to enable only what you need. ### Quick Start: Recommended Configurations #### Starter (core + json + text) If you prefer in … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [neverinfamous](https://github.com/neverinfamous) - **Source:** [neverinfamous/db-mcp](https://github.com/neverinfamous/db-mcp) - **License:** MIT - **Homepage:** https://search.adamic.tech/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** yes *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-neverinfamous-db-mcp - Seller: https://agentstack.voostack.com/s/neverinfamous - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.