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）。

行为准则

参与本项目前，请阅读我们的行为准则。