Db MCP

🚀 db-mcp

企業級SQLite MCP服務器，具備OAuth 2.1認證和89個專業工具

db-mcp是一個強大的SQLite MCP服務器，提供了豐富的工具集和安全認證機制，可滿足企業級數據庫管理和分析的需求。它支持多種數據庫操作，包括統計分析、文本處理、向量搜索等，同時具備OAuth 2.1認證和細粒度的訪問控制，確保數據的安全性和可靠性。

---

🚀 快速開始

✅ 快速測試 - 驗證一切正常

在30秒內測試服務器！

構建並運行：

npm run build
node dist/cli.js --transport stdio --sqlite-native :memory:

預期輸出：

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

運行測試套件：

npm run test

🛡️ 安全特性

• ✅ SQL注入防護 - 所有查詢均使用參數綁定
• ✅ OAuth 2.1認證 - 符合RFC 9728/8414標準
• ✅ 基於範圍的授權 - 細粒度的讀/寫/管理訪問權限
• ✅ 嚴格的TypeScript - 完全類型安全，無any類型

⬆️ 返回目錄

🚀 快速啟動

選項1：Docker（推薦）

立即拉取並運行：

docker pull writenotenow/db-mcp:latest

使用卷掛載運行：

docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/db-mcp:latest \
  --sqlite-native /workspace/database.db

選項2：Node.js安裝

克隆倉庫：

git clone https://github.com/neverinfamous/db-mcp.git

進入目錄：

cd db-mcp

安裝依賴：

npm install

構建項目：

npm run build

運行服務器：

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

⬆️ 返回目錄

⚡ 安裝到Cursor IDE

一鍵安裝

點擊下面的按鈕直接安裝到Cursor：

或者複製這個深度鏈接：

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

前提條件

• ✅ 已安裝並運行Docker（使用Docker方法時）
• ✅ Node.js 18+（本地安裝時）

⬆️ 返回目錄

---

📦 安裝指南

環境變量配置

將.env.example複製為.env並進行配置：

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配置

請參考config/db-mcp.keycloak.json獲取完整示例。

---

💻 使用示例

數據分析工作流

1. 構建項目：

npm run build

2. 使用你的數據啟動：

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

3. 與Claude/Cursor一起使用，進行以下操作：
   • 對數據集進行統計分析
   • 文本處理和模式提取
   • 向量相似度搜索
   • 地理空間分析和地圖繪製

JSON操作

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

// 使用路徑提取查詢JSON
sqlite_json_extract({
  table: "products",
  column: "metadata",
  path: "$.price"
})

向量/語義搜索

// 存儲嵌入向量
sqlite_vector_store({
  table: "documents",
  id_column: "id",
  embedding_column: "embedding",
  id: 1,
  embedding: [0.1, 0.2, 0.3, ...]
})

// 查找相似項
sqlite_vector_search({
  table: "documents",
  embedding_column: "embedding",
  query_embedding: [0.15, 0.25, 0.35, ...],
  top_k: 10
})

全文搜索（FTS5）

// 創建FTS5索引
sqlite_fts_create({
  table: "articles",
  columns: ["title", "content"]
})

// 使用BM25排名進行搜索
sqlite_fts_search({
  table: "articles",
  query: "machine learning",
  limit: 10
})

統計分析

// 獲取列的描述性統計信息
sqlite_describe_stats({
  table: "employees",
  column: "salary"
})
// 返回：計數、均值、標準差、最小值、25%分位數、50%分位數、75%分位數、最大值

// 計算分位數
sqlite_percentile({
  table: "sales",
  column: "revenue",
  percentiles: [25, 50, 75, 90, 95, 99]
})

// 生成直方圖
sqlite_histogram({
  table: "products",
  column: "price",
  bins: 10
})

地理空間操作

// 計算兩點之間的距離（Haversine公式）
sqlite_geo_distance({
  lat1: 40.7128,
  lon1: -74.0060,  // 紐約
  lat2: 34.0522,
  lon2: -118.2437  // 洛杉磯
})
// 返回：距離（公里）

// 查找邊界框內的位置
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
})

// 對附近的點進行聚類
sqlite_geo_cluster({
  table: "customers",
  lat_column: "lat",
  lon_column: "lon",
  distance_km: 5
})

窗口函數（僅原生後端）

// 為查詢結果添加行號
sqlite_window_row_number({
  table: "employees",
  order_by: "hire_date",
  partition_by: "department"
})

// 計算排名
sqlite_window_rank({
  table: "sales",
  value_column: "revenue",
  partition_by: "region",
  rank_type: "dense_rank"  // 或者 "rank", "percent_rank"
})

// 計算累計總和
sqlite_window_running_total({
  table: "transactions",
  value_column: "amount",
  order_by: "date",
  partition_by: "account_id"
})

// 移動平均
sqlite_window_moving_avg({
  table: "stock_prices",
  value_column: "close_price",
  order_by: "date",
  window_size: 7  // 7天移動平均
})

事務（僅原生後端）

// 原子性地執行多個語句
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)"
  ]
})
// 所有語句要麼全部成功，要麼全部回滾

// 使用保存點進行手動事務控制
sqlite_transaction_begin({ mode: "immediate" })
sqlite_transaction_savepoint({ name: "before_update" })
// ... 執行操作 ...
sqlite_transaction_rollback_to({ name: "before_update" })  // 如果需要，回滾到保存點
sqlite_transaction_commit()

文本處理

// 正則表達式模式匹配
sqlite_regex_match({
  table: "logs",
  column: "message",
  pattern: "ERROR:\\s+(\\w+)"
})

// 模糊搜索拼寫錯誤
sqlite_fuzzy_search({
  table: "products",
  column: "name",
  query: "laptp",  // 拼寫錯誤的 "laptop"
  threshold: 0.6
})

// 文本相似度評分
sqlite_text_similarity({
  text1: "machine learning",
  text2: "deep learning",
  algorithm: "levenshtein"  // 或者 "jaro_winkler", "cosine"
})

⬆️ 返回目錄

---

📚 詳細文檔

📊 工具類別

類別	WASM	原生	描述
核心數據庫	8	8	CRUD、模式、索引、視圖
JSON助手	6	6	簡化的JSON操作
JSON操作	12	12	完整的JSON操作
文本處理	8	8	正則表達式、大小寫、子字符串
FTS5全文搜索	4	4	創建、搜索、重建
統計分析	8	8	統計、百分位數、直方圖
虛擬表	4	4	生成序列
向量/語義	11	11	嵌入、相似度搜索
地理空間	7	7	距離、邊界框、聚類
管理	4	4	清理、備份、分析、優化
事務	—	7	開始、提交、回滾、保存點
窗口函數	—	6	行號、排名、滯後/超前、累計總和
總計	76	89

SQLite後端選項

根據需求選擇兩種SQLite後端之一：

特性	WASM (sql.js)	原生 (better-sqlite3)
可用工具	76	89
事務	❌	✅ 7個工具
窗口函數	❌	✅ 6個工具
FTS5全文搜索	⚠️ 有限	✅ 完整
JSON1擴展	⚠️ 有限	✅ 完整
跨平臺	✅ 無需編譯	需要Node.js原生構建
內存數據庫	✅	✅
基於文件的數據庫	✅	✅

僅原生的事務工具 (7個)

工具	描述
sqlite_transaction_begin	開始事務（延遲/立即/排他模式）
sqlite_transaction_commit	提交當前事務
sqlite_transaction_rollback	回滾當前事務
sqlite_transaction_savepoint	創建保存點
sqlite_transaction_release	釋放保存點
sqlite_transaction_rollback_to	回滾到保存點
sqlite_transaction_execute	原子性地執行多個語句

僅原生的窗口函數工具 (6個)

工具	描述
sqlite_window_row_number	分配連續的行號
sqlite_window_rank	計算排名/DENSE_RANK/PERCENT_RANK
sqlite_window_lag_lead	訪問前一行或後一行的值
sqlite_window_running_total	計算累計總和
sqlite_window_moving_avg	計算移動平均值
sqlite_window_ntile	將行劃分為N個桶（四分位數、十分位數等）

⬆️ 返回目錄

📚 MCP客戶端配置

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

內存數據庫

使用:memory:創建臨時內存數據庫：

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

⬆️ 返回目錄

🎛️ 工具過濾預設

⚠️ 重要提示

像Cursor這樣的支持AI的IDE有工具數量限制。由於原生後端有89個工具，你必須使用工具過濾來保持在限制範圍內。根據你的用例選擇下面的預設。

工具組

組	工具數量	描述
core	9	基本的CRUD、模式、表
json	11	JSON操作
text	6	文本處理（正則表達式、模糊匹配）
fts5	4	全文搜索
stats	8	統計分析
performance	6	查詢分析、優化
vector	8	嵌入、相似度搜索
geo	7	地理空間操作
backup	4	數據庫備份/恢復
monitoring	5	健康檢查、資源使用情況
admin	10	清理、分析、編譯指示
transactions	7	事務控制（僅原生）
window	6	窗口函數（僅原生）

預設：最小集（約35個工具） ⭐ 推薦給大多數用戶

核心數據庫操作，包括JSON和基本文本處理。最適合一般開發。

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

預設：分析集（約56個工具）

包括統計、窗口函數和文本處理。適用於數據分析。

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

預設：搜索集（約62個工具）

全文搜索加上向量/語義搜索功能。

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

預設：地理空間集（約48個工具）

距離計算、邊界框和空間查詢。

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

自定義過濾

使用以下語法創建自己的過濾器：

• -group — 禁用組中的所有工具
• -tool_name — 禁用特定工具
• +tool_name — 在禁用組後重新啟用工具

# 示例：禁用向量和地理空間工具，但保留餘弦相似度工具
--tool-filter "-vector,-geo,+cosine_similarity"

⬆️ 返回目錄

---

✨ 主要特性

🔥 核心功能

• 📊 統計分析 - 描述性統計、百分位數、時間序列分析
• 🔍 高級文本處理 - 正則表達式、模糊匹配、語音搜索、相似度
• 🧠 向量/語義搜索 - AI原生嵌入、餘弦相似度、混合搜索
• 🗺️ 地理空間操作 - 距離計算、邊界框、空間查詢
• 🔐 事務安全 - 具有保存點的完整ACID合規性（原生後端）
• 🎛️ 89個專業工具 - 完整的數據庫管理和分析套件

🏢 企業特性

• 🔐 OAuth 2.1認證 - 符合RFC 9728/8414的基於令牌的認證
• 🛡️ 工具過濾 - 控制暴露哪些數據庫操作
• 👥 訪問控制 - 細粒度的只讀、寫入和管理訪問範圍
• 🎯 全文搜索（FTS5） - 具有BM25排名的高級搜索
• ⚡ 窗口函數 - 行號、排名、累計總和、移動平均值

⬆️ 返回目錄

🔐 OAuth 2.1實現

組件	狀態	描述
受保護資源元數據	✅	RFC 9728 /.well-known/oauth-protected-resource
認證服務器發現	✅	具有緩存的RFC 8414元數據發現
令牌驗證	✅	支持JWKS的JWT驗證
範圍強制	✅	細粒度的read、write、admin範圍
HTTP傳輸	✅	可流式傳輸的HTTP，帶有OAuth中間件

支持的範圍

範圍	描述
read	對所有數據庫的只讀訪問
write	對所有數據庫的讀寫訪問
admin	完全管理訪問
db:{name}	僅訪問特定數據庫
table:{db}:{table}	僅訪問特定表

Keycloak集成

有關將Keycloak設置為OAuth提供程序的信息，請參閱docs/KEYCLOAK_SETUP.md。

⬆️ 返回目錄

---

🏆 為什麼選擇db-mcp？

✅ 原生TypeScript - 嚴格模式下的完全類型安全，無any類型
✅ 89個專業工具 - 可用的最全面的SQLite MCP服務器
✅ 內置OAuth 2.1 - 開箱即用的企業級認證
✅ 雙後端 - WASM實現可移植性，原生後端提供高性能
✅ 工具過濾 - 使用預設配置保持在AI IDE工具限制範圍內
✅ 窗口函數 - 具有ROW_NUMBER、RANK、LAG/LEAD的高級分析
✅ 事務支持 - 具有保存點的完整ACID合規性
✅ 現代架構 - 基於MCP SDK構建，設計簡潔、模塊化
✅ 積極開發 - 定期更新和改進

⬆️ 返回目錄

---

📈 項目統計

• 原生後端有89個工具（WASM有76個）
• 13個工具組，便於靈活過濾
• 嚴格的TypeScript，具有完整的類型覆蓋
• 多平臺支持（Windows、Linux、macOS）
• 提供Docker鏡像，便於部署
• OAuth 2.1符合RFC標準的認證
• 積極開發，定期更新

⬆️ 返回目錄

---

📄 許可證

本項目採用MIT許可證 - 有關詳細信息，請參閱LICENSE文件。

---

貢獻

歡迎貢獻！提交拉取請求前，請閱讀我們的貢獻指南。

安全

有關安全問題，請參閱我們的安全策略。

⚠️ 重要提示

切勿提交憑據 - 將機密信息存儲在.env文件中（已添加到.gitignore）。

行為準則

參與本項目前，請閱讀我們的行為準則。