writenotenow/db-mcp repository overview

⁠db-mcp (SQLite MCP Server)

Production-ready SQLite MCP server with 170+ tools, audit logging, OAuth 2.1, and Code Mode.

GitHub⁠ • Wiki⁠ • Changelog⁠

⁠🎯 What Sets Us Apart

⁠Backend Options

⁠🚀 Quick Start

⁠1. Pull the Image

docker pull writenotenow/db-mcp:latest

⁠2. Run with MCP Client

Add to your ~/.cursor/mcp.json or Claude Desktop config:

{
  "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"
      ]
    }
  }
}

⁠3. Restart & Query!

Restart Cursor or your MCP client and start querying SQLite databases!

⁠Prerequisites

• ✅ Docker installed and running
• ✅ ~200MB disk space available

⁠🎛️ Tool Filtering

⁠Recommended Configurations

The Quick Start above uses Code Mode (--tool-filter codemode) — the recommended default. If you prefer individual tool calls instead:

⁠Starter (core + json + text)

starter provides Core + JSON + Text:

{
  "args": ["--tool-filter", "starter"]
}

⁠Custom Groups

Specify exactly the groups you need:

{
  "args": ["--tool-filter", "core,json,stats"]
}

⁠Shortcuts (Predefined Bundles)

⁠Tool Groups (10 Available)

10 granular tool groups (e.g., core, json, text, stats, vector, admin) let you precisely control exposed capabilities. For advanced syntax (whitelisting individual tools, additive + and subtractive - filters) and the complete tool group list, refer to the GitHub Repository⁠.

⁠🛡️ Supply Chain Security

For enhanced security, use SHA-pinned multi-arch manifests (docker pull writenotenow/db-mcp:sha256-<digest>). Our images feature cryptographic build provenance, SBOMs, non-root execution, and zero critical/high CVEs (Docker Scout scanned). Find exact tags on Docker Hub⁠.

⁠📁 Resources & Prompts

db-mcp exposes 22 resources (including dynamic sqlite://help documentation) and 10 AI-powered prompts (for schema exploration, query building, data analysis, optimization, and migration). See the GitHub README⁠ for the complete list.

⁠SQLite Extensions

The Docker image includes FTS5, JSON1, and R-Tree built-in. Enable loadable extensions via CLI flags:

⁠🔧 Configuration

⁠Environment Variables

⁠HTTP/SSE Transport

For remote access or web-based clients:

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0 --sqlite-native /app/data/database.db --allowed-io-roots /app/data

Endpoints:

Security: 7 security headers, server timeouts (slowloris protection), rate limiting (100/min, 429 + Retry-After), CORS deny-all default (explicit corsOrigins config required), trust proxy (trustedProxyIps), body size limit (--max-body-bytes, default 1MB), opt-in HSTS, cross-protocol session guard.

⁠🔐 Authentication

Full OAuth 2.1 with RFC 9728/8414 compliance:

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0 \
  --oauth-enabled --oauth-issuer http://keycloak:8080/realms/db-mcp --oauth-audience db-mcp-server \
  --sqlite-native /app/data/database.db \
  --allowed-io-roots /app/data

Scopes: full, read, write, admin, db:{name}, table:{db}:{table}. See Keycloak Setup⁠ for provider configuration.

⁠🔐 Encryption at Rest (Native Only)

db-mcp supports transparent database encryption using SQLCipher via the --encryption-key CLI flag or DB_ENCRYPTION_KEY environment variable.

For advanced configuration (raw hex keys vs passphrases, dual-backend audit log encryption rules, and migration steps), please see the full Security Documentation⁠.

⁠📦 Image Details

Node.js 24 on Alpine Linux • Multi-stage build • Non-root user • better-sqlite3 native

Available Tags:

• v5.0.1 - Specific version (recommended for production)
• latest - Always the newest version
• sha-<commit> - Git commit pinned

⁠📚 Documentation & Resources

• GitHub Wiki⁠ — Complete documentation
• Build from Source⁠ — Clone, build, and run locally
• Issues⁠ — Bug reports & feature requests

⁠📄 License

MIT License - See LICENSE⁠