Skip to main content
Glama
neverinfamous

db-mcp

by neverinfamous
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

db-mcp

Last Updated January 31, 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.

Beta - This project is actively being developed and is not yet ready for production use.

GitHub License: MIT CodeQL Version Status Security TypeScript

Wiki • Changelog • Security

📋 Table of Contents

Quick Start

Configuration & Usage

Features & Resources

✅ Quick Test - Verify Everything Works

Test the server in 30 seconds!

Build and run:

npm run build # Option 1: Native backend (better-sqlite3) node dist/cli.js --transport stdio --sqlite-native :memory: # Option 2: WASM backend (sql.js) node dist/cli.js --transport stdio --sqlite :memory:

Expected output (native):

[db-mcp] Starting MCP server... [db-mcp] Registered adapter: Native SQLite Adapter (better-sqlite3) (sqlite:default) [db-mcp] Server started successfully

Expected output (WASM):

[db-mcp] Starting MCP server... [db-mcp] Registered adapter: WASM SQLite Adapter (sql.js) (sqlite:default) [db-mcp] Server started successfully

Run the test suite:

npm run test

🛡️ Security Features

  • ✅ SQL Injection Prevention - Parameter binding on all queries

  • ✅ OAuth 2.1 Authentication - RFC 9728/8414 compliant

  • ✅ Scope-based Authorization - Granular read/write/admin access

  • ✅ Strict TypeScript - Full type safety with no any types

⬆️ Back to Table of Contents

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

⬆️ Back to Table of Contents

⚡ Install to Cursor IDE

One-Click Installation

Click the button below to install directly into Cursor:

Install to 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)

⬆️ Back to Table of Contents

📊 Tool Categories

Category

WASM

Native

Description

Core Database

8

8

CRUD, schema, indexes, views

JSON Helpers

8

8

Simplified JSON operations, schema analysis

JSON Operations

15

15

Full JSON manipulation, JSONB support

Text Processing

13

13

Regex, fuzzy, phonetic, advanced search

FTS5 Full-Text Search

4

4

Create, search, rebuild, optimize

Statistical Analysis

13

19

Stats, outliers, regression + window functions

Virtual Tables

13

13

CSV, R-Tree, series, views, vacuum, dbstat

Vector/Semantic

11

11

Embeddings, similarity search

Geospatial

4

11

Distance, bounding box + SpatiaLite GIS

Admin/PRAGMA

13

20

Backup, restore, pragmas, transactions

Total

102

122

SQLite Backend Options

Choose between two SQLite backends based on your needs:

Feature

WASM (sql.js)

Native (better-sqlite3)

Tools Available

102

122

Transactions

❌

✅ 7 tools

Window Functions

❌

✅ 6 tools

FTS5 Full-Text Search

⚠️ Limited

✅ Full

JSON1 Extension

⚠️ Limited

✅ Full

Cross-platform

✅ No compilation

Requires Node.js native build

In-memory DBs

✅

✅

File-based DBs

✅

✅

Transaction Tools (7) - Native Only

Tool

Description

sqlite_transaction_begin

Start transaction (deferred/immediate/exclusive mode)

sqlite_transaction_commit

Commit current transaction

sqlite_transaction_rollback

Rollback current transaction

sqlite_transaction_savepoint

Create a savepoint

sqlite_transaction_release

Release a savepoint

sqlite_transaction_rollback_to

Rollback to a savepoint

sqlite_transaction_execute

Execute multiple statements atomically

Window Function Tools (6) - Native Only

Tool

Description

sqlite_window_row_number

Assign sequential row numbers

sqlite_window_rank

Calculate RANK/DENSE_RANK/PERCENT_RANK

sqlite_window_lag_lead

Access previous or next row values

sqlite_window_running_total

Calculate cumulative sums

sqlite_window_moving_avg

Calculate rolling averages

sqlite_window_ntile

Divide rows into N buckets (quartiles, deciles, etc.)

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

sqlite_schema

sqlite://schema

Full database schema (tables, indexes)

sqlite_tables

sqlite://tables

List all tables in the database

sqlite_table_schema

sqlite://table/{name}/schema

Schema for a specific table

sqlite_indexes

sqlite://indexes

All indexes in the database

sqlite_views

sqlite://views

All views in the database

sqlite_health

sqlite://health

Database health and connection status

sqlite_meta

sqlite://meta

Database metadata and configuration

sqlite_insights

memo://insights

Business insights memo (analysis)

💬 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

⬆️ Back to Table of Contents

⚡ Performance Tuning

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

Variable

Default

Description

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

⬆️ Back to Table of Contents

📚 MCP Client Configuration

Cursor IDE (Native Backend)

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

Cursor IDE (WASM Backend)

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

Claude Desktop (Native)

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

Claude Desktop (WASM)

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

Native with Extensions (CSV + SpatiaLite)

To enable loadable extensions, add CLI flags and set environment variables for extension paths:

Windows:

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

Linux/macOS:

{ "mcpServers": { "db-mcp-sqlite": { "command": "node", "args": [ "/path/to/db-mcp/dist/cli.js", "--transport", "stdio", "--sqlite-native", "/path/to/database.db", "--csv", "--spatialite", "--tool-filter", "starter" ], "env": { "CSV_EXTENSION_PATH": "/path/to/extensions/csv.so", "SPATIALITE_PATH": "/usr/lib/x86_64-linux-gnu/mod_spatialite.so" } } } }

Note: Extension flags (--csv, --spatialite) are only available with the native backend (--sqlite-native). Set environment variables if extensions are not in standard system paths.

Docker with Claude Desktop

{ "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 --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 --stateless --sqlite-native :memory:

Mode

Progress Notifications

SSE Streaming

Serverless

Stateful (default)

✅ Yes

✅ Yes

⚠️ Complex

Stateless (--stateless)

❌ No

❌ No

✅ Native

⬆️ Back to Table of Contents

🎛️ 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.

Quick Start: Recommended Configurations

Option 1: Starter (18 tools) ⭐ Recommended

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

Option 2: Analytics (23 tools)

Core + JSON + Stats + Window functions. For data analysis.

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

Option 3: Search (14 tools)

Core + Text + FTS5 + Vector. For search workloads.

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

Option 4: 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

17

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"

⬆️ Back to Table of Contents

🔥 Core Capabilities

  • 📊 Statistical Analysis - Descriptive stats, percentiles, time series analysis

  • 🔍 Advanced Text Processing - Regex, fuzzy matching, phonetic search, similarity

  • 🧠 Vector/Semantic Search - AI-native embeddings, cosine similarity, hybrid search

  • 🗺️ Geospatial Operations - Distance calculations, bounding boxes, spatial queries

  • 🔐 Transaction Safety - Full ACID compliance with savepoints (native backend)

  • 🎛️ 122 Specialized Tools - Complete database administration and analytics suite

🏢 Enterprise Features

  • 🔐 OAuth 2.1 Authentication - RFC 9728/8414 compliant token-based authentication

  • 🛡️ Tool Filtering - Control which database operations are exposed

  • 👥 Access Control - Granular scopes for read-only, write, and admin access

  • 🎯 Full-Text Search (FTS5) - Advanced search with BM25 ranking

  • ⚡ Window Functions - Row numbers, rankings, running totals, moving averages

⬆️ Back to Table of Contents

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

⬆️ Back to Table of Contents

🏆 Why Choose db-mcp?

✅ TypeScript Native - Full type safety with strict mode, no any types
✅ 122 Specialized Tools - Most comprehensive SQLite MCP server available
✅ OAuth 2.1 Built-in - Enterprise-grade authentication out of the box
✅ Dual Backends - WASM for portability, native for performance
✅ Tool Filtering - Stay within AI IDE tool limits with preset configurations
✅ Window Functions - Advanced analytics with ROW_NUMBER, RANK, LAG/LEAD
✅ Transaction Support - Full ACID compliance with savepoints
✅ Modern Architecture - Built on MCP SDK with clean, modular design
✅ Active Development - Regular updates and improvements

⬆️ Back to Table of Contents

📈 Project Stats

  • 122 Tools in native backend (102 in WASM)

  • 13 Tool Groups for flexible filtering

  • Strict TypeScript with full type coverage

  • Multi-platform support (Windows, Linux, macOS)

  • Docker images available for easy deployment

  • OAuth 2.1 RFC-compliant authentication

  • Active development with regular updates

⬆️ Back to Table of Contents

Configuration

Environment Variables

Copy .env.example to .env and configure:

KEYCLOAK_URL=http://localhost:8080 KEYCLOAK_REALM=db-mcp KEYCLOAK_CLIENT_ID=db-mcp-server KEYCLOAK_CLIENT_SECRET=your_secret_here DBMCP_PORT=3000 DBMCP_OAUTH_ENABLED=true

JSON Configuration

See config/db-mcp.keycloak.json for a complete 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.

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/neverinfamous/db-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server