db-mcp

Last Updated December 12, 2025

Enterprise-grade SQLite MCP Server with OAuth 2.0 authentication & 89 specialized tools

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

A SQLite MCP Server with up to 89 tools, OAuth 2.0 authentication, and granular access control. Written in TypeScript.

Wiki • Changelog • Security

---

📋 Table of Contents

Quick Start

• ✅ Quick Test - Verify Everything Works
• 🚀 Quick Start
• ⚡ Install to Cursor IDE

Configuration & Usage

• 📚 MCP Client Configuration
• 🎛️ Tool Filtering Presets
• 🎨 Usage Examples
• 📊 Tool Categories

Features & Resources

• 🔥 Core Capabilities
• 🔐 OAuth 2.0 Implementation
• 🏆 Why Choose db-mcp?
• 📈 Project Stats

---

✅ Quick Test - Verify Everything Works

Test the server in 30 seconds!

Build and run:

npm run build
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

🛡️ Security Features

• ✅ SQL Injection Prevention - Parameter binding on all queries
• ✅ OAuth 2.0 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:

node dist/cli.js --transport stdio --sqlite-native ./database.db

⬆️ Back to Table of Contents

---

⚡ 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 18+ (for local installation)

⬆️ Back to Table of Contents

---

📊 Tool Categories

| Category | WASM | Native | Description | |----------|------|--------|-------------| | Core Database | 8 | 8 | CRUD, schema, indexes, views | | JSON Helpers | 6 | 6 | Simplified JSON operations | | JSON Operations | 12 | 12 | Full JSON manipulation | | Text Processing | 8 | 8 | Regex, case, substring | | FTS5 Full-Text Search | 4 | 4 | Create, search, rebuild | | Statistical Analysis | 8 | 8 | Stats, percentiles, histograms | | Virtual Tables | 4 | 4 | Generate series | | Vector/Semantic | 11 | 11 | Embeddings, similarity search | | Geospatial | 7 | 7 | Distance, bounding box, clustering | | Admin | 4 | 4 | Vacuum, backup, analyze, optimize | | Transactions | — | 7 | Begin, commit, rollback, savepoints | | Window Functions | — | 6 | Row number, rank, lag/lead, running totals | | Total | 76 | 89 | |

SQLite Backend Options

Choose between two SQLite backends based on your needs:

| Feature | WASM (sql.js) | Native (better-sqlite3) | |---------|---------------|-------------------------| | Tools Available | 76 | 89 | | 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.) |

⬆️ Back to Table of Contents

---

📚 MCP Client Configuration

Cursor IDE

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

Claude Desktop

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

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

⬆️ Back to Table of Contents

---

🎛️ Tool Filtering Presets

[!IMPORTANT] AI-enabled IDEs like Cursor have tool limits. With 89 tools in the native backend, you must use tool filtering to stay within limits. Choose a preset below based on your use case.

Tool Groups

| Group | Tools | Description | |-------|-------|-------------| | core | 9 | Basic CRUD, schema, tables | | json | 11 | JSON operations | | text | 6 | Text processing (regex, fuzzy) | | fts5 | 4 | Full-text search | | stats | 8 | Statistical analysis | | performance | 6 | Query analysis, optimization | | vector | 8 | Embeddings, similarity search | | geo | 7 | Geospatial operations | | backup | 4 | Database backup/restore | | monitoring | 5 | Health checks, resource usage | | admin | 10 | Vacuum, analyze, pragmas | | transactions | 7 | Transaction control (native only) | | window | 6 | Window functions (native only) |

Preset: Minimal (~35 tools) ⭐ Recommended for most users

Core database operations with JSON and basic 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", "-stats,-vector,-geo,-backup,-monitoring,-transactions,-window"
      ]
    }
  }
}

Preset: Analytics (~56 tools)

Includes statistics, window functions, and text processing. For data analysis.

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

Preset: Search (~62 tools)

Full-text search plus vector/semantic search capabilities.

{
  "args": [
    "--transport", "stdio",
    "--sqlite-native", "C:/path/to/database.db",
    "--tool-filter", "-stats,-geo,-backup,-monitoring,-transactions,-window"
  ]
}

Preset: Geospatial (~48 tools)

Distance calculations, bounding boxes, and spatial queries.

{
  "args": [
    "--transport", "stdio",
    "--sqlite-native", "C:/path/to/database.db",
    "--tool-filter", "-stats,-vector,-backup,-monitoring,-transactions,-window"
  ]
}

Custom Filtering

Create your own filter using the syntax:

• -group — Disable all tools in a group
• -tool_name — Disable a specific tool
• +tool_name — Re-enable a tool after group disable

# Example: Disable vector and geo, but keep cosine_similarity
--tool-filter "-vector,-geo,+cosine_similarity"

⬆️ Back to Table of Contents

---

🎨 Usage Examples

Data Analysis Workflow

1. Build the project:

npm run build

2. Start with your data:

node dist/cli.js --transport stdio --sqlite-native ./sales_data.db

3. Use with Claude/Cursor for:
   • Statistical analysis of your datasets
   • Text processing and pattern extraction
   • Vector similarity search
   • Geospatial analysis and mapping

JSON Operations

// Insert JSON data
sqlite_write_query({
  query: "INSERT INTO products (metadata) VALUES (?)",
  params: [JSON.stringify({ name: "Product", price: 29.99 })]
})

// Query JSON with path extraction
sqlite_json_extract({
  table: "products",
  column: "metadata",
  path: "$.price"
})

Vector/Semantic Search

// Store embeddings
sqlite_vector_store({
  table: "documents",
  id_column: "id",
  embedding_column: "embedding",
  id: 1,
  embedding: [0.1, 0.2, 0.3, ...]
})

// Find similar items
sqlite_vector_search({
  table: "documents",
  embedding_column: "embedding",
  query_embedding: [0.15, 0.25, 0.35, ...],
  top_k: 10
})

Full-Text Search (FTS5)

// Create FTS5 index
sqlite_fts_create({
  table: "articles",
  columns: ["title", "content"]
})

// Search with BM25 ranking
sqlite_fts_search({
  table: "articles",
  query: "machine learning",
  limit: 10
})

Statistical Analysis

// Get descriptive statistics for a column
sqlite_describe_stats({
  table: "employees",
  column: "salary"
})
// Returns: count, mean, std, min, 25%, 50%, 75%, max

// Calculate percentiles
sqlite_percentile({
  table: "sales",
  column: "revenue",
  percentiles: [25, 50, 75, 90, 95, 99]
})

// Generate histogram
sqlite_histogram({
  table: "products",
  column: "price",
  bins: 10
})

Geospatial Operations

// Calculate distance between two points (Haversine formula)
sqlite_geo_distance({
  lat1: 40.7128,
  lon1: -74.0060,  // New York
  lat2: 34.0522,
  lon2: -118.2437  // Los Angeles
})
// Returns: distance in kilometers

// Find locations within bounding box
sqlite_geo_bounding_box({
  table: "stores",
  lat_column: "latitude",
  lon_column: "longitude",
  min_lat: 40.0,
  max_lat: 41.0,
  min_lon: -75.0,
  max_lon: -73.0
})

// Cluster nearby points
sqlite_geo_cluster({
  table: "customers",
  lat_column: "lat",
  lon_column: "lon",
  distance_km: 5
})

Window Functions (Native Only)

// Add row numbers to query results
sqlite_window_row_number({
  table: "employees",
  order_by: "hire_date",
  partition_by: "department"
})

// Calculate rankings
sqlite_window_rank({
  table: "sales",
  value_column: "revenue",
  partition_by: "region",
  rank_type: "dense_rank"  // or "rank", "percent_rank"
})

// Calculate running totals
sqlite_window_running_total({
  table: "transactions",
  value_column: "amount",
  order_by: "date",
  partition_by: "account_id"
})

// Moving averages
sqlite_window_moving_avg({
  table: "stock_prices",
  value_column: "close_price",
  order_by: "date",
  window_size: 7  // 7-day moving average
})

Transactions (Native Only)

// Execute multiple statements atomically
sqlite_transaction_execute({
  statements: [
    "UPDATE accounts SET balance = balance - 100 WHERE id = 1",
    "UPDATE accounts SET balance = balance + 100 WHERE id = 2",
    "INSERT INTO transfers (from_id, to_id, amount) VALUES (1, 2, 100)"
  ]
})
// All statements succeed or all are rolled back

// Manual transaction control with savepoints
sqlite_transaction_begin({ mode: "immediate" })
sqlite_transaction_savepoint({ name: "before_update" })
// ... perform operations ...
sqlite_transaction_rollback_to({ name: "before_update" })  // Undo if needed
sqlite_transaction_commit()

Text Processing

// Regex pattern matching
sqlite_regex_match({
  table: "logs",
  column: "message",
  pattern: "ERROR:\\s+(\\w+)"
})

// Fuzzy search for misspellings
sqlite_fuzzy_search({
  table: "products",
  column: "name",
  query: "laptp",  // Misspelled "laptop"
  threshold: 0.6
})

// Text similarity scoring
sqlite_text_similarity({
  text1: "machine learning",
  text2: "deep learning",
  algorithm: "levenshtein"  // or "jaro_winkler", "cosine"
})

⬆️ 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)
• 🎛️ 89 Specialized Tools - Complete database administration and analytics suite

🏢 Enterprise Features

• 🔐 OAuth 2.0 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.0 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.

⬆️ Back to Table of Contents

---

🏆 Why Choose db-mcp?

✅ TypeScript Native - Full type safety with strict mode, no any types
✅ 89 Specialized Tools - Most comprehensive SQLite MCP server available
✅ OAuth 2.0 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

• 89 Tools in native backend (76 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.0 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.