db-mcp (SQLite MCP Server)

SQLite MCP Server with 139 specialized tools, 8 data resources + 9 help resources, and 10 prompts, 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.

Wiki • Changelog

🎯 What Sets Us Apart

🚀 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:

npm install

Build the project:

npm run build

Run the server:

# Native backend (better-sqlite3) - Full features, requires Node.js native build
node dist/cli.js --transport stdio --sqlite-native ./database.db

# 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 (139 tools, transactions, window functions, SpatiaLite). Use --sqlite for WASM mode (115 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:

npm run test

Prerequisites

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

🎛️ Tool Filtering

[!IMPORTANT] AI-enabled IDEs like Cursor have tool limits. With 139 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

⭐ Recommended: Code Mode (Maximum Token Savings)

Code Mode (sqlite_execute_code) provides access to all 139 tools' worth of capability through a single, secure JavaScript sandbox. Instead of spending thousands of tokens on back-and-forth tool calls, Code Mode exposes all capabilities locally — reducing token overhead by up to 90%.

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "C:/path/to/db-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--sqlite-native",
        "C:/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 9 tool groups, and returning exactly the data it needs — in one execution.

Starter (50 tools)

If you prefer individual tool calls, 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)

Note: Native includes FTS5 (4), window functions (6), transactions (7), and SpatiaLite (7) not available in WASM.

Tool Groups (10 Available)

Note: +3 built-in tools (server_info, server_health, list_adapters) and +1 code mode are always included.

Syntax Reference

Custom Tool Selection

You can list individual tool names (without + prefix) to create a fully custom whitelist — only the tools you specify will be enabled:

# Enable exactly 3 tools (whitelist mode)
--tool-filter "read_query,write_query,list_tables"

# Mix tools from different groups
--tool-filter "read_query,fuzzy_search,vector_search"

# Combine with a shortcut or group
--tool-filter "starter,+vector_search,+fuzzy_search"

This is useful for scripted or automated clients that need a minimal, precise set of capabilities.

Examples:

--tool-filter "starter"
--tool-filter "core,json,text,fts5"
--tool-filter "starter,+stats"
--tool-filter "starter,-fts5"

Legacy Syntax (still supported): If you start with a negative filter (e.g., -vector,-geo), it assumes you want to start with all tools enabled and then subtract.

--tool-filter "-stats,-vector,-geo,-backup,-monitoring,-transactions,-window"

� SQLite Extensions

SQLite supports both built-in extensions (compiled into better-sqlite3) and loadable extensions (require separate binaries).

Built-in Extensions (work out of box)

Loadable Extensions (require installation)

Installing Extensions

CSV Extension:

# Download precompiled binary or compile from SQLite source:
# https://www.sqlite.org/csv.html

# Set environment variable:
export CSV_EXTENSION_PATH=/path/to/csv.so  # Linux
export CSV_EXTENSION_PATH=/path/to/csv.dll # Windows

# Or use CLI flag:
db-mcp --sqlite-native ./data.db --csv

SpatiaLite Extension:

# Linux (apt):
sudo apt install libspatialite-dev

# macOS (Homebrew):
brew install libspatialite

# Windows: Download from https://www.gaia-gis.it/gaia-sins/

# Set environment variable:
export SPATIALITE_PATH=/path/to/mod_spatialite.so

# Or use CLI flag:
db-mcp --sqlite-native ./data.db --spatialite

Note: Extension binaries must match your platform and architecture. The server searches common paths automatically, or use the CSV_EXTENSION_PATH / SPATIALITE_PATH environment variables for custom locations.

📁 Resources

Data Resources (8)

MCP resources provide read-only access to database metadata:

Help Resources (1 + up to 8)

On-demand tool reference documentation, filtered by --tool-filter:

Efficiency Tip: Data resources are always readable regardless of tool configuration. The "Min Config" column shows the smallest configuration that provides tools to act on what the resource exposes. Help resources are served on-demand — agents read them only when working with a specific tool group.

💬 Prompts (10)

MCP prompts provide AI-assisted database workflows:

🔧 Configuration

Environment Variables

Tip: Lower METADATA_CACHE_TTL_MS for development (e.g., 1000), or increase it for production with stable schemas (e.g., 60000 = 1 min). Schema cache is automatically invalidated on DDL operations (CREATE/ALTER/DROP).

CLI Reference

db-mcp [options]

Transport:    --transport <stdio|http|sse>  --port <N>  --server-host <host>  --stateless
Auth:         --auth-token <token>  |  --oauth-enabled --oauth-issuer <url> --oauth-audience <aud>
Database:     --sqlite <path>  |  --sqlite-native <path>
Extensions:   --csv  --spatialite                         (native only)
Server:       --name <name>  --version <ver>  --tool-filter <filter>

CLI flags override environment variables. Run node dist/cli.js --help for full details.

📚 MCP Client Configuration

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

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

Variants (modify the args array above):

See Tool Filtering to customize which tools are exposed.

HTTP/SSE Transport (Remote Access)

For remote access, web-based clients, or MCP Inspector testing, run the server in HTTP mode:

node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --sqlite-native ./database.db

Endpoints:

Session Management: The server uses stateful sessions by default. Include the mcp-session-id header (returned from initialization) in subsequent requests for session continuity.

Security Features:

• 7 Security Headers — X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, Cache-Control, Referrer-Policy (no-referrer), Permissions-Policy + opt-in Strict-Transport-Security via enableHSTS
• Server Timeouts — Request, keep-alive, and headers timeouts prevent slowloris-style DoS
• Rate Limiting — 100 requests/minute per IP (429 + Retry-After on excess, health checks exempt)
• CORS — Configurable via --cors-origins (default: *, supports wildcard subdomains like *.example.com). ⚠️ Security Warning: The default * allows requests from any origin. For production HTTP deployments, explicitly configure this to your trusted domains.
• Trust Proxy — Opt-in trustProxy for X-Forwarded-For IP extraction behind reverse proxies
• Body Size Limit — Configurable via --max-body-bytes (default: 1 MB)
• 404 Handler — Unknown paths return { error: "Not found" }
• Cross-Protocol Guard — SSE session IDs rejected on /mcp and vice versa

Stateless Mode (Serverless)

For serverless deployments (AWS Lambda, Cloudflare Workers, Vercel), use stateless mode:

node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --stateless --sqlite-native :memory:

🔐 Authentication

db-mcp supports two authentication mechanisms for HTTP transport:

Simple Bearer Token (--auth-token)

Lightweight authentication for development or single-tenant deployments:

# CLI
node dist/cli.js --transport http --port 3000 --auth-token my-secret --sqlite-native ./database.db

# Environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --port 3000 --sqlite-native ./database.db

Clients must include Authorization: Bearer my-secret on all requests. /health and / are exempt. Unauthenticated requests receive 401 with WWW-Authenticate: Bearer headers per RFC 6750.

OAuth 2.1 (Enterprise)

Full OAuth 2.1 with RFC 9728/8414 compliance for production multi-tenant deployments:

Supported Scopes

Quick Start with OAuth CLI Flags

node dist/cli.js --transport http --port 3000 \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/db-mcp \
  --oauth-audience db-mcp-server \
  --sqlite-native ./database.db

Additional flags: --oauth-jwks-uri <url> (auto-discovered if omitted), --oauth-clock-tolerance <seconds> (default: 60).

Keycloak Integration

See docs/KEYCLOAK_SETUP.md for setting up Keycloak as your OAuth provider.

Priority: When both --auth-token and --oauth-enabled are set, OAuth 2.1 takes precedence. If neither is configured, the server warns and runs without authentication.

📊 Benchmarks

Performance benchmarks measure framework overhead on critical hot paths using Vitest bench (tinybench). The suite validates that framework plumbing stays negligible relative to actual database I/O:

• Tool dispatch: ~11M ops/sec — Map-based lookup is effectively zero-cost
• Auth scope checks: 7–9M ops/sec — OAuth middleware adds no measurable latency
• Identifier validation: 6.4M ops/sec — SQL sanitization is near-instant
• Schema cache hits: 4.3M ops/sec — metadata lookups avoid redundant queries
• Debug log (filtered): 9.5M ops/sec — disabled log levels are true no-ops (50× faster than actual writes)
• Code Mode security: 1.2M validations/sec for typical code, blocked patterns rejected in <1 µs

npm run bench            # Run all benchmarks
npm run bench:verbose    # Verbose mode with detailed timings

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

Security

For security concerns, please see our Security Policy.

⚠️ Never commit credentials - Store secrets in .env (gitignored)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

Please read our Code of Conduct before participating in this project.