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.

Name		Name	Last commit message	Last commit date
Latest commit History 295 Commits
.github		.github
config		config
docs		docs
releases		releases
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER_README.md		DOCKER_README.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

db-mcp (SQLite MCP Server)

🎯 What Sets Us Apart

🚀 Quick Start

Option 1: Docker (Recommended)

Option 2: Node.js Installation

Verify It Works

⚡ Install to Cursor IDE

One-Click Installation

Prerequisites

🎛️ Tool Filtering

Quick Start: Recommended Configurations

⭐ Recommended: Starter (48 tools)

Custom Groups

Shortcuts (Predefined Bundles)

Tool Groups (7 Available)

Syntax Reference

� SQLite Extensions

Built-in Extensions (work out of box)

Loadable Extensions (require installation)

Installing Extensions

📁 Resources (8)

💬 Prompts (10)

⚡ Performance Tuning

📚 MCP Client Configuration

Cursor IDE / Claude Desktop

Native with Extensions (CSV + SpatiaLite)

Docker

In-Memory Database

HTTP/SSE Transport (Remote Access)

Stateless Mode (Serverless)

🔐 OAuth 2.1 Implementation

Supported Scopes

Keycloak Integration

Quick Start with OAuth

Contributing

Security

License

Code of Conduct

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Uh oh!

Contributors

Uh oh!

Languages