Quick Start

Quick Start

Get db-mcp running in under 5 minutes.

---

Prerequisites

• Docker installed and running (for Docker method)
• Node.js 24+ LTS (for local installation)

---

Installation Options

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 (From Source)

git clone https://github.com/neverinfamous/db-mcp.git
cd db-mcp
pnpm install
pnpm run build

Run the server with Native backend (better-sqlite3 — full features):

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

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

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

Option 3: npm

pnpm install db-mcp

---

MCP Client Configuration

Cursor IDE / Claude Desktop / AntiGravity

Add to your MCP configuration file (~/.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "/path/to/db-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--sqlite-native",
        "/path/to/your/database.db",
        "--tool-filter",
        "codemode"
      ]
    }
  }
}

Note: Code Mode (--tool-filter codemode) is the recommended default — a single tool providing access to all capabilities via a secure sandbox. See Tool Filtering for alternatives.

Docker Configuration

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "./data:/app/data",
        "writenotenow/db-mcp:latest",
        "--sqlite-native",
        "/app/data/database.db",
        "--tool-filter",
        "codemode"
      ]
    }
  }
}

Docker Note: Volume-mount your database directory so the container can access it.

Configuration Variants

Variant	Change
WASM backend	Replace --sqlite-native with --sqlite
In-memory database	Replace the database path with :memory:
Encryption at Rest	Add "--encryption-key" followed by your key (native only)
Starter preset	Replace "codemode" with "starter" for individual tool calls
CSV extension	Add "--csv" before "--tool-filter" (native only)
SpatiaLite	Add "--spatialite" and set SPATIALITE_PATH env var (native only)
Configuration File	Add "--config" followed by the path to your .yaml or .json file
Linux/macOS	Use forward-slash Unix paths

---

Backend Choice

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	⚠️ Blocks event loop	🚀 High-performance

Use --sqlite-native for production and full features. Use --sqlite for zero-dependency portability.

---

Verify Installation

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

---

Next Steps

• Tool Filtering — Configure tool presets for your IDE
• HTTP Transport — Remote access via Streamable HTTP or legacy SSE
• Code Mode — Enable 70–90% token reduction
• Extensions — Enable FTS5, SpatiaLite, and CSV extensions
• Tool Reference — Explore all tools by group