SQLite数据库MCP服务器

Prerequisites

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

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 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 (151 tools, transactions, window functions, SpatiaLite). Use --sqlite for WASM mode (125 tools, no native dependencies).

🚀 Quick Start

Quick Start: Recommended Configurations

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

🔧 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).

📚 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.

Or via 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.

Syntax Reference

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)
Audit:        --audit-log <path>  --audit-redact  --audit-reads  --audit-backup  --audit-backup-data
Server:       --name <name>  --version <ver>  --tool-filter <filter>

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

Utility Endpoints

🔌 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 a precompiled binary or compile from source: https://www.sqlite.org/csv.html

Set the environment variable (Linux/macOS):

export CSV_EXTENSION_PATH=/path/to/csv.so

On Windows, use .dll:

export CSV_EXTENSION_PATH=/path/to/csv.dll

Or use the CLI flag:

db-mcp --sqlite-native ./data.db --csv

SpatiaLite Extension:

Install the library for your platform:

• Linux (apt): sudo apt install libspatialite-dev
• macOS (Homebrew): brew install libspatialite
• Windows: Download from https://www.gaia-gis.it/gaia-sins/

Set the environment variable:

export SPATIALITE_PATH=/path/to/mod_spatialite.so

Or use the 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.