Db Mcp

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 • [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, tableschema, indexes, views, health, meta, audit, metrics, compileoptions, 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:

docker pull writenotenow/db-mcp:latest

Run with volume mount:

docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/db-mcp:latest \
  --sqlite-native /workspace/database.db

Option 2: Node.js Installation

Clone the repository:

git clone https://github.com/neverinfamous/db-mcp.git

Navigate to directory:

cd db-mcp

Install dependencies:

pnpm install

Build the project:

pnpm run build

Run the server with Native backend (better-sqlite3 — full features, requires Node.js native build):

node dist/cli.js --transport stdio --sqlite-native ./database.db

Or with WASM backend (sql.js — cross-platform, no compilation required):

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

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:

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:

{
  "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 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
• Source: neverinfamous/db-mcp
• License: MIT
• Homepage: https://search.adamic.tech/

Install and usage instructions live in the source repository linked above.