db-mcp (SQLite MCP Server)

Last Updated February 23, 2026

SQLite MCP Server with HTTP/SSE Transport, OAuth 2.1 authentication, smart tool filtering, granular access control, 122 specialized tools, 8 resources, and 10 prompts. Available in WASM and better-sqlite3 variants.

Wiki • Changelog

---

🎯 What Sets Us Apart

Feature	Description
122 Specialized Tools	The most comprehensive SQLite MCP server available — core CRUD, JSON/JSONB, FTS5 full-text search, statistical analysis, vector search, geospatial/SpatiaLite, and admin
8 Resources	Schema, tables, indexes, views, health status, database metadata, and business insights — always readable regardless of tool configuration
10 AI-Powered Prompts	Guided workflows for schema exploration, query building, data analysis, optimization, migration, debugging, and hybrid FTS5 + vector search
Dual SQLite Backends	WASM (sql.js) for zero-compilation portability, Native (better-sqlite3) for full features including transactions, window functions, and SpatiaLite GIS
OAuth 2.1 + Access Control	Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (read, write, admin, db:*, table:*:*), and Keycloak integration
Smart Tool Filtering	7 tool groups + 6 shortcuts let you stay within IDE limits while exposing exactly what you need
HTTP Streaming Transport	SSE-based streaming with /mcp and /health endpoints for remote deployments, plus stateless mode for serverless
Structured Error Handling	Tools return {success, error} responses with actionable context — designed for agent consumption rather than cryptic error codes
Production-Ready Security	SQL injection prevention via parameter binding, input validation, non-root Docker execution, and build provenance
Strict TypeScript	100% type-safe codebase with strict mode, no any types
MCP 2025-11-25 Compliant	Full protocol support with tool safety hints, 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:

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 (122 tools, transactions, window functions, SpatiaLite). Use --sqlite for WASM mode (102 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

⚡ Install to Cursor IDE

One-Click Installation

Click the button below to install directly into Cursor:

Or copy this deep link:

cursor://anysphere.cursor-deeplink/mcp/install?name=db-mcp-sqlite&config=eyJkYi1tY3Atc3FsaXRlIjp7ImFyZ3MiOlsicnVuIiwiLWkiLCItLXJtIiwiLXYiLCIkKHB3ZCk6L3dvcmtzcGFjZSIsIndyaXRlbm90ZW5vdy9kYi1tY3A6bGF0ZXN0IiwiLS1zcWxpdGUtbmF0aXZlIiwiL3dvcmtzcGFjZS9kYXRhYmFzZS5kYiJdLCJjb21tYW5kIjoiZG9ja2VyIn19

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

AntiGravity Users: Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal usage in AntiGravity, manually provide the contents of src/constants/ServerInstructions.ts to the agent in your prompt or user rules.

Quick Start: Recommended Configurations

⭐ Recommended: Starter (48 tools)

Core + JSON + Text. Best for general development.

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

Custom Groups

Specify exactly the groups you need:

{
  "args": [
    "--transport",
    "stdio",
    "--sqlite-native",
    "C:/path/to/database.db",
    "--tool-filter",
    "core,json,stats"
  ]
}

Shortcuts (Predefined Bundles)

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

Shortcut	WASM	Native	+ Built-in	What's Included
starter	48	48	+3	Core, JSON, Text
analytics	44	50	+3	Core, JSON, Stats
search	36	36	+3	Core, Text, Vector
spatial	23	30	+3	Core, Geo, Vector
minimal	8	8	+3	Core only
full	102	122	+3	Everything enabled

Tool Groups (7 Available)

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

Group	WASM	Native	+ Built-in	Description
core	8	8	+3	Basic CRUD, schema, tables
json	23	23	+3	JSON/JSONB operations, analysis
text	13	17	+3	Text processing + FTS5 + advanced search
stats	13	19	+3	Statistical analysis (+ window funcs)
vector	11	11	+3	Embeddings, similarity search
admin	26	33	+3	Backup, restore, virtual tables, pragma
geo	4	11	+3	Geospatial + SpatiaLite (Native only)

Syntax Reference

Prefix	Target	Example	Effect
(none)	Shortcut	starter	Whitelist Mode: Enable ONLY this shortcut
(none)	Group	core	Whitelist Mode: Enable ONLY this group
+	Group	+vector	Add tools from this group to current set
-	Group	-admin	Remove tools in this group from current set
+	Tool	+fuzzy_search	Add one specific tool
-	Tool	-drop_table	Remove one specific tool

Examples:

# Use a shortcut
--tool-filter "starter"

# Combine groups (whitelist mode)
--tool-filter "core,json,text,fts5"

# Extend a shortcut
--tool-filter "starter,+stats"

# Exclude from a shortcut
--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.

# Legacy: start with all, exclude some
--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)

Extension	Purpose	Status
FTS5	Full-text search with BM25 ranking	✅ Always loaded
JSON1	JSON functions (json_extract, etc.)	✅ Always loaded
R-Tree	Spatial indexing for bounding boxes	✅ Always loaded

Loadable Extensions (require installation)

Extension	Purpose	Tools	CLI Flag
CSV	CSV virtual tables	2	--csv
SpatiaLite	Advanced GIS capabilities	7	--spatialite

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 (8)

MCP resources provide read-only access to database metadata:

Resource	URI	Description	Min Config
sqlite_schema	sqlite://schema	Full database schema	minimal
sqlite_tables	sqlite://tables	List all tables	minimal
sqlite_table_schema	sqlite://table/{name}/schema	Schema for a specific table	minimal
sqlite_indexes	sqlite://indexes	All indexes in the database	minimal
sqlite_views	sqlite://views	All views in the database	core,admin
sqlite_health	sqlite://health	Database health and status	(read-only)
sqlite_meta	sqlite://meta	Database metadata and PRAGMAs	core,admin
sqlite_insights	memo://insights	Business insights memo (analysis)	core,admin

Efficiency Tip: 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. Use --tool-filter "core,admin" (~18 tools) instead of full (102+) when you only need resource-related functionality.

💬 Prompts (10)

MCP prompts provide AI-assisted database workflows:

Prompt	Description
sqlite_explain_schema	Explain database structure and relationships
sqlite_query_builder	Help construct SQL queries for common operations
sqlite_data_analysis	Analyze data patterns and provide insights
sqlite_optimization	Analyze and suggest database optimizations
sqlite_migration	Help create database migration scripts
sqlite_debug_query	Debug SQL queries that aren't working
sqlite_documentation	Generate documentation for the database schema
sqlite_summarize_table	Intelligent table analysis and summary
sqlite_hybrid_search_workflow	Hybrid FTS5 + vector search workflow
sqlite_demo	Interactive demo of MCP capabilities

⚡ Performance Tuning

Schema metadata is cached to reduce repeated queries during tool/resource invocations.

Variable	Default	Description
MCP_HOST	0.0.0.0	Host/IP to bind to (HTTP transport)
METADATA_CACHE_TTL_MS	5000	Cache TTL for schema metadata (milliseconds)
LOG_LEVEL	info	Log verbosity: debug, info, warning, error

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

Cursor IDE / Claude Desktop

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

Notes:

• For WASM backend, replace --sqlite-native with --sqlite
• For Linux/macOS, use forward-slash Unix paths (e.g., /path/to/db-mcp/dist/cli.js)
• See Tool Filtering to customize which tools are exposed

Native with Extensions (CSV + SpatiaLite)

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "C:/path/to/db-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--sqlite-native",
        "C:/path/to/database.db",
        "--csv",
        "--spatialite",
        "--tool-filter",
        "starter"
      ],
      "env": {
        "SPATIALITE_PATH": "C:/path/to/extensions/mod_spatialite.dll"
      }
    }
  }
}

Notes:

• Extension flags (--csv, --spatialite) require the native backend (--sqlite-native)
• Set CSV_EXTENSION_PATH and/or SPATIALITE_PATH env vars if extensions are not in standard system paths
• For Linux/macOS, use Unix paths and .so extensions (e.g., SPATIALITE_PATH=/usr/lib/x86_64-linux-gnu/mod_spatialite.so)

Docker

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/workspace",
        "writenotenow/db-mcp:latest",
        "--sqlite-native",
        "/workspace/database.db"
      ]
    }
  }
}

In-Memory Database

Use :memory: for a temporary in-memory database:

{
  "args": ["--transport", "stdio", "--sqlite-native", ":memory:"]
}

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:

Endpoint	Description
GET /	Server info and available endpoints
POST /mcp	JSON-RPC requests (initialize, tools/call)
GET /mcp	SSE stream for server-to-client notifications
DELETE /mcp	Session termination
GET /health	Health check (always public)

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

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:

Mode	Progress Notifications	SSE Streaming	Serverless
Stateful (default)	✅ Yes	✅ Yes	⚠️ Complex
Stateless (--stateless)	❌ No	❌ No	✅ Native

🔐 OAuth 2.1 Implementation

Component	Status	Description
Protected Resource Metadata	✅	RFC 9728 /.well-known/oauth-protected-resource
Auth Server Discovery	✅	RFC 8414 metadata discovery with caching
Token Validation	✅	JWT validation with JWKS support
Scope Enforcement	✅	Granular read, write, admin scopes
HTTP Transport	✅	Streamable HTTP with OAuth middleware

Supported Scopes

Scope	Description
read	Read-only access to all databases
write	Read and write access to all databases
admin	Full administrative access
db:{name}	Access to specific database only
table:{db}:{table}	Access to specific table only

Keycloak Integration

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

Quick Start with OAuth

1. Start the server with OAuth enabled:

# Set environment variables
export KEYCLOAK_URL=http://localhost:8080
export KEYCLOAK_REALM=db-mcp
export KEYCLOAK_CLIENT_ID=db-mcp-server

# Start server with HTTP transport and OAuth
node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --sqlite-native ./database.db

2. Get an access token from Keycloak:

# Using cURL
curl -X POST "http://localhost:8080/realms/db-mcp/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=db-mcp-server" \
  -d "client_secret=YOUR_SECRET" \
  -d "username=testuser" \
  -d "password=YOUR_PASSWORD" \
  -d "grant_type=password" \
  -d "scope=openid read write"

3. Make authenticated MCP requests:

# Initialize session with Bearer token
curl -X POST "http://localhost:3000/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'

Note: OAuth is automatically enabled when running in HTTP mode with OAuth environment variables configured. The /.well-known/oauth-protected-resource endpoint provides RFC 9728 metadata for client discovery.

Configuration files: Copy .env.example for a quick-start template. See config/db-mcp.keycloak.json for a complete Keycloak configuration example.

---

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.