db-mcp (SQLite MCP Server)
SQLite MCP server with OAuth 2.1, HTTP/SSE, 122 tools, and smart tool filtering
Ask AI about db-mcp (SQLite MCP Server)
Powered by Claude Β· Grounded in docs
I know everything about db-mcp (SQLite MCP Server). Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
π― 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-nativefor full features (122 tools, transactions, window functions, SpatiaLite). Use--sqlitefor 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.tsto 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_PATHenvironment 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 offull(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_MSfor 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-nativewith--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_PATHand/orSPATIALITE_PATHenv vars if extensions are not in standard system paths - For Linux/macOS, use Unix paths and
.soextensions (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-resourceendpoint provides RFC 9728 metadata for client discovery.
Configuration files: Copy
.env.examplefor a quick-start template. Seeconfig/db-mcp.keycloak.jsonfor 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.
