db-mcp (SQLite MCP Server)

db-mcp（SQLite MCP Server）

SQLite MCP Server，包含 170 多个专用工具、11 个数据资源和 11 个帮助资源，以及 10 个提示词；支持带 DDL 备份快照的审计日志、HTTP/SSE 传输、OAuth 2.1 身份验证、工具筛选、细粒度访问控制，以及提供分类且可操作响应的结构化错误处理。提供 WASM 和 better-sqlite3 版本。

Wiki • 更新日志

---

🎯 我们的独特之处

特性	描述
181+ 个专用工具	功能最全面的 SQLite MCP 服务 — 涵盖核心 CRUD、JSON/JSONB、FTS5 全文搜索、统计分析、向量搜索、地理空间/SpatiaLite、内省、迁移和管理
深度可观测性	内置 Prometheus /metrics 导出、实时 sqlite://metrics MCP 资源、持久化到 SystemDb 边车数据库的历史数据，以及用于合规与调查的细粒度 sqlite_audit_search 工具
动态配置	完整支持 YAML/JSON 配置文件（--config）及优先级规则，并提供 sqlite_server_config 工具，可实时更新运行时配置（例如日志级别），无需重启服务
高级查询与搜索	O(1) 基于游标的键集分页、分面搜索聚合，以及通过单次工具调用协调 FTS5 与向量相似度、使用倒数排名融合（RRF）的 sqlite_hybrid_search
AI 索引建议	sqlite_index_audit 会自动分析 EXPLAIN QUERY PLAN 响应，根据工作负载模式建议优化的复合索引和部分索引
实时订阅	原生支持 resources/subscribe，可将由事件驱动的 sqlite://schema DDL 变更通知和定期 sqlite://health 更新直接推送给客户端
22 个资源	11 个数据资源（schema、tables、table_schema、indexes、views、health、meta、audit、metrics、compile_options、pragma）+ 11 个帮助资源（sqlite://help + 按组分类的参考资料）— 可通过 --tool-filter 过滤
10 个 AI 驱动的提示词	用于引导用户探索 schema、构建查询、分析数据、优化、迁移、调试以及混合 FTS5 + 向量搜索的工作流
代码模式	大幅节省 Token： 在 V8 隔离沙箱中执行复杂的多步骤操作，并具备进程级隔离和严格超时机制。无需花费数千个 Token 进行来回工具调用，代码模式即可在本地提供全部 180+ 项功能，将 Token 开销降低 70–90%，大幅增强 AI Agent 的推理能力
针对 Token 优化的负载	每个工具响应都经过精简设计，并在每个响应中附带 _meta.tokenEstimate，让 Agent 了解其 Token 成本。适用时，工具提供 compact、nodesOnly、maxOutliers、minSeverity 和 maxInvalid 参数，让 Agent 在不失去数据访问能力的情况下控制响应大小
双 SQLite 后端	WASM（sql.js）实现零编译移植性；Native（better-sqlite3）支持高性能并发执行及完整功能，包括事务、窗口函数和 SpatiaLite GIS
OAuth 2.1 + 访问控制	满足企业需求的安全性，符合 RFC 9728/8414，支持细粒度作用域（full、read、write、admin、db:*、table:*:*）以及 Keycloak 集成
智能工具过滤	10 个工具组 + 7 个快捷方式，让你在符合 IDE 限制的同时，精准开放所需功能
HTTP 流式传输	面向现代客户端的可流式 HTTP（/mcp）+ 为向后兼容提供的旧版 SSE（/sse）— 两种协议可同时使用，并支持安全标头、速率限制、健康检查以及适用于无服务器场景的无状态模式
适用于生产环境的安全性	SQL 注入防护（参数化查询 + 经 Unicode 规范化的 WHERE 子句验证）、沙箱化代码执行（V8 codeGeneration 限制、冻结原型、29 种禁用模式、禁用 Proxy、RPC 允许列表）、默认拒绝所有 CORS、失败时默认拒绝的作用域强制执行、JWT 声明净化、7 个安全标头、请求体大小限制、带 Retry-After 的速率限制、slowloris 超时、trustedProxyIps、选择启用的 HSTS、非 root Docker，以及构建来源证明
静态加密	通过 --encryption-key 或 DB_ENCRYPTION_KEY 原生支持 SQLCipher。动态加载 better-sqlite3-multiple-ciphers，并自动加密边车 SystemDb 中的审计日志，防止敏感查询泄露
严格 TypeScript	100% 类型安全的代码库，采用严格模式，不使用 any 类型；包含 1911 个单元测试 + 1136 个 E2E 测试，覆盖率达 90%
确定性错误处理	每个工具都返回结构化的 {success, error, code, category, suggestion, recoverable} 响应 — 不会返回原始异常，也不会静默失败。Agent 可获得包含可执行建议的丰富错误上下文，而非晦涩的 SQLite 错误代码
符合 MCP 2025-03-26 规范	完整支持协议，包括工具安全提示（sensitiveHint、readOnlyHint）、资源优先级和进度通知

🚀 快速开始

选项 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

安装依赖：

pnpm install

构建项目：

pnpm run build

使用 原生后端（better-sqlite3 — 功能完整，需要 Node.js 原生构建）运行服务：

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

或使用 WASM 后端（sql.js — 跨平台，无需编译）运行：

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

后端选择： 使用 --sqlite-native 可获得完整功能（181 个 MCP 工具 / 170 个分组工具、事务、窗口函数、SpatiaLite）。使用 --sqlite 可启用 WASM 模式（154 个 MCP 工具 / 143 个分组工具，无原生依赖）。

验证是否正常运行

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

运行测试套件：

pnpm run test

前提条件

• ✅ 已安装并运行 Docker（用于 Docker 方式）
• ✅ Node.js 24+（LTS）（用于本地安装）

代码模式：最高效率

代码模式（sqlite_execute_code）可大幅降低 Token 使用量（70–90%），并默认包含在所有预设中。

代码在工作线程沙箱中执行——这是一个拥有独立内存空间的 V8 隔离环境。所有 sqlite.* API 调用都会通过基于 MessagePort 的 RPC 桥接转发到主线程，由主线程执行实际的数据库操作。这提供了：

• 进程级隔离 — 用户代码在独立的 V8 实例中运行，并受到强制堆限制
• 只读强制执行 — 当 readonly: true 时，被移除的方法会通过 Proxy 陷阱抛出清晰的错误消息，并列出可用方法
• 硬超时 — 如果执行时间超过配置的限制，则终止工作线程
• V8 代码生成限制 — 通过 codeGeneration: { strings: false, wasm: false } 在 V8 引擎级别禁用从字符串执行 eval() 和构造 Function()
• RPC 允许列表 — 主机端验证可阻止工作线程调用未经授权的 API 方法
• 完整 API 访问 — 所有 10 个工具组都可通过 sqlite.* 使用（例如，sqlite.core.readQuery()、sqlite.json.extract()）

如有需要，可设置 CODEMODE_ISOLATION=vm 和 CODEMODE_ISOLATION_INSECURE=1，回退到进程内的 vm 模块沙箱。

⚡ 仅启用代码模式（最大限度节省 Token）

如果您可以自行控制设置，则可以仅启用代码模式运行——通过 sqlite.* API 提供相当于 180 多个工具能力的单个工具：

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

这只会公开 sqlite_execute_code 和内置工具。Agent 使用类型化的 sqlite.* SDK 编写 JavaScript，通过一次执行组合查询、串联跨越所有 10 个工具组的操作，并返回所需的数据。这与 Cloudflare 为其整个 API 首创的代码模式方案相似：无论能力数量多少，Token 成本都固定不变。

提示

最大限度节省 Token： 指示您的 AI Agent 优先使用代码模式，而不是单独调用工具：

"使用 db-mcp 时，对于多步骤数据库操作，优先使用 sqlite_execute_code（代码模式），以尽量减少 Token 使用量。"

---

🎛️ 工具筛选

重要

Cursor 等支持 AI 的 IDE 有工具数量限制。 原生后端有 180 多个工具，必须使用工具筛选才能满足限制。使用快捷配置或指定工具组，仅启用所需功能。

快速开始：推荐配置

入门配置（core + json + text）

如果您更喜欢单独调用工具，starter 会提供 Core + JSON + Text：

{
  "args": ["--tool-filter", "starter"]
}

自定义工具组

准确指定所需的工具组：

{
  "args": ["--tool-filter", "core,json,stats"]
}

快捷方式（预定义工具包）

注意： Native 包含 WASM 中不可用的 FTS5（5）、窗口函数（6）、事务（8）和 SpatiaLite（7）。

快捷方式	WASM	Native	+ 内置	包含内容
starter	65	70	+4	核心、JSON、文本
analytics	67	73	+4	核心、JSON、统计
search	51	56	+4	核心、文本、向量
spatial	40	47	+4	核心、地理、向量
dev-schema	41	41	+4	核心、自省、迁移
minimal	25	25	+4	仅核心
full	143	170	+4	启用所有功能

工具组（提供 10 个）

注意： 每个组都会注入 +4 个内置工具（server_info、server_health、list_adapters、sqlite_execute_code）。

组	WASM	Native	+ 内置	描述
core	25	25	+4	基本 CRUD、架构、表
json	25	25	+4	JSON/JSONB 操作、分析
text	15	20	+4	文本处理 + FTS5 + 高级搜索
stats	17	23	+4	描述统计、推断统计、窗口函数
vector	11	11	+4	向量存储、相似性搜索
admin	30	31	+4	数据库维护、备份、虚拟表
transactions	0	8	+4	提交、回滚、保存点（仅 Native）
geo	4	11	+4	地理空间 + SpatiaLite（仅 Native）
introspection	10	10	+4	架构映射、外键关系图、分析
migration	6	6	+4	架构迁移跟踪（选择启用）

语法参考

前缀	目标	示例	效果
(无)	快捷方式	starter	**白名单模式：**仅启用此快捷方式
(无)	组	core	**白名单模式：**仅启用此组
(无)	工具	read_query	**白名单模式：**仅启用此工具
+	组	+vector	将此组中的工具添加到当前集合
-	组	-admin	从当前集合中移除此组中的工具
+	工具	+fuzzy_search	添加一个指定工具
-	工具	-drop_table	移除一个指定工具

自定义工具选择

你可以列出单个工具名称（不带 + 前缀）来创建完全自定义的白名单——只有你指定的工具会启用：

恰好启用 3 个工具（白名单模式）：

--tool-filter "read_query,write_query,list_tables"

混合使用不同组中的工具：

--tool-filter "read_query,fuzzy_search,vector_search"

与快捷方式或组组合使用：

--tool-filter "starter,+vector_search,+fuzzy_search"

这适用于需要一组精简且精确功能的脚本化或自动化客户端。

示例：

--tool-filter "starter"
--tool-filter "core,json,text,stats"
--tool-filter "starter,+stats"
--tool-filter "starter,-vector"

旧语法（仍受支持）： 如果你以负向筛选器开头（例如 -vector,-geo），系统会假定你想先启用_所有_工具，再将其逐一移除。

--tool-filter "-stats,-vector,-geo,-backup,-monitoring,-transactions,-window"

🔌 SQLite 扩展

SQLite 同时支持内置扩展（编译到 better-sqlite3 中）和可加载扩展（需要单独的二进制文件）。

内置扩展（开箱即用）

扩展	用途	状态
FTS5	支持 BM25 排序的全文搜索	✅ 始终加载
JSON1	JSON 函数（json_extract 等）	✅ 始终加载
R-Tree	用于边界框的空间索引	✅ 始终加载

可加载扩展（需要安装）

扩展	用途	工具	CLI 标志
CSV	CSV 虚拟表	2	--csv
SpatiaLite	高级 GIS 功能	7	--spatialite

安装扩展

CSV 扩展：

下载预编译二进制文件或从源代码编译：https://www.sqlite.org/csv.html

设置环境变量（Linux/macOS）：

export CSV_EXTENSION_PATH=/path/to/csv.so

在 Windows 上，使用 .dll：

export CSV_EXTENSION_PATH=/path/to/csv.dll

或使用 CLI 标志：

db-mcp --sqlite-native ./data.db --csv

SpatiaLite 扩展：

为你的平台安装该库：

• Linux (apt)： sudo apt install libspatialite-dev
• macOS (Homebrew)： brew install libspatialite
• Windows： 从 https://www.gaia-gis.it/gaia-sins/ 下载

设置环境变量：

export SPATIALITE_PATH=/path/to/mod_spatialite.so

或使用 CLI 标志：

db-mcp --sqlite-native ./data.db --spatialite

注意： 扩展二进制文件必须与平台和架构匹配。服务会自动搜索常见路径，也可以使用 CSV_EXTENSION_PATH / SPATIALITE_PATH 环境变量指定自定义位置。

📁 资源

数据资源（11）

MCP 资源提供对数据库元数据的只读访问：

资源	URI	描述	最低配置
sqlite_schema	sqlite://schema	完整数据库架构	minimal
sqlite_tables	sqlite://tables	列出所有表	minimal
sqlite_table_schema	sqlite://table/{tableName}/schema	特定表的架构	minimal
sqlite_indexes	sqlite://indexes	数据库中的所有索引	minimal
sqlite_views	sqlite://views	数据库中的所有视图	core,admin
sqlite_health	sqlite://health	数据库健康状况和状态	(只读)
sqlite_meta	sqlite://meta	数据库元数据和 PRAGMA	core,admin
sqlite_compile_options	sqlite://compile_options	SQLite 编译时构建选项	(只读)
sqlite_pragma	sqlite://pragma	运行时 PRAGMA 配置快照	(只读)
sqlite_audit	sqlite://audit	最近的审计日志和备份统计信息	--audit-log
sqlite_metrics	sqlite://metrics	服务内部指标	(只读)

帮助资源（1 + 最多 10 个）

按需提供的工具参考文档，可通过 --tool-filter 筛选：

资源	URI	描述	注册时机
sqlite_help	sqlite://help	注意事项、WASM 与 Native 的区别、Code Mode API	始终
sqlite_help_core	sqlite://help/core	核心 CRUD 和表操作参考	启用 core 组时
sqlite_help_json	sqlite://help/json	JSON/JSONB 操作参考	启用 json 组时
sqlite_help_text	sqlite://help/text	文本处理和 FTS5 参考	启用 text 组时
sqlite_help_stats	sqlite://help/stats	统计分析和窗口函数参考	启用 stats 组时
sqlite_help_vector	sqlite://help/vector	向量/语义搜索参考	启用 vector 组时
sqlite_help_geo	sqlite://help/geo	地理空间和 SpatiaLite 参考	启用 geo 组时
sqlite_help_admin	sqlite://help/admin	管理、备份、虚拟表参考	启用 admin 组时
sqlite_help_transactions	sqlite://help/transactions	事务控制参考	启用 transactions 组时
sqlite_help_introspection	sqlite://help/introspection	架构自省、外键关系图和诊断参考	启用 introspection 组时
sqlite_help_migration	sqlite://help/migration	迁移跟踪、应用和回滚参考	启用 migration 组时

效率提示： 无论工具配置如何，数据资源始终都可以读取。“最小配置”列显示了可对资源所提供内容进行操作的工具所需的最小配置。帮助资源按需提供——Agent 仅在使用特定工具组时才会读取它们。

💬 提示词（10 个）

MCP 提示词提供 AI 辅助的数据库工作流：

提示词	描述
sqlite_explain_schema	说明数据库结构和关系
sqlite_query_builder	帮助构建常见操作所需的 SQL 查询
sqlite_data_analysis	分析数据模式并提供见解
sqlite_optimization	分析并提出数据库优化建议
sqlite_migration	帮助创建数据库迁移脚本
sqlite_debug_query	调试无法正常运行的 SQL 查询
sqlite_documentation	为数据库架构生成文档
sqlite_summarize_table	智能分析并总结表
sqlite_hybrid_search_workflow	混合 FTS5 + 向量搜索工作流
sqlite_demo	交互式演示 MCP 功能

🔧 配置

环境变量

变量	默认值	描述
MCP_HOST	127.0.0.1	要绑定的主机/IP（在 Docker 中为 0.0.0.0）（CLI：--server-host）
SQLITE_DATABASE	—	SQLite 数据库路径（CLI：--sqlite / --sqlite-native）
DB_ENCRYPTION_KEY	—	SQLCipher 加密密钥（仅限 Native）（CLI：--encryption-key）
DB_MCP_TOOL_FILTER	—	工具筛选字符串（CLI：--tool-filter）
METRICS_EXPORT	—	通过 HTTP /metrics 导出指标（例如：prometheus）（CLI：--metrics-export）
OAUTH_ENABLED	false	启用 OAuth 2.1（CLI：--oauth-enabled）
OAUTH_ISSUER	—	授权服务器 URL（CLI：--oauth-issuer）
OAUTH_AUDIENCE	—	预期的令牌受众（CLI：--oauth-audience）
OAUTH_JWKS_URI	—	JWKS URI，省略时自动发现（CLI：--oauth-jwks-uri）
OAUTH_CLOCK_TOLERANCE	60	时钟容差（秒）（CLI：--oauth-clock-tolerance）
MCP_ENABLE_HSTS	false	启用 HSTS 标头（CLI：--enable-hsts）
NO_AUTH_ENFORCEMENT	false	明确绕过 HTTP 身份验证强制机制（CLI：--no-auth-enforcement）
LOG_LEVEL	info	日志详细程度：debug、info、warning、error
METADATA_CACHE_TTL_MS	5000	架构缓存 TTL（毫秒）（DDL 操作时自动失效）
CODEMODE_ISOLATION	isolate	Code Mode 沙箱：isolate（isolated-vm native）或 worker
CODE_MODE_MAX_RESULT_SIZE	102400	Code Mode 结果负载的最大字节数（默认 100KB，上限 50MB）
MCP_RATE_LIMIT_MAX	100	每个 IP 每分钟的最大请求数（HTTP 传输）
CSV_EXTENSION_PATH	—	CSV 扩展二进制文件的自定义路径（仅限 native）
SPATIALITE_PATH	—	SpatiaLite 扩展二进制文件的自定义路径（仅限 native）
ALLOWED_IO_ROOTS	—	允许用于 IO 操作的绝对路径 JSON 数组或逗号分隔列表
MCP_AUTH_TOKEN	—	用于 HTTP 身份验证的简单 bearer 令牌（CLI：--auth-token）
AUDIT_LOG	—	审计日志文件路径，或 stderr（CLI：--audit-log）
AUDIT_REDACT	true	对审计条目中的工具参数进行脱敏（使用 CLI：--audit-no-redact 禁用）
AUDIT_READS	false	同时记录读取范围的工具调用（CLI：--audit-reads）
AUDIT_BACKUP	false	启用变更前的 DDL 快照（CLI：--audit-backup）
AUDIT_BACKUP_DATA	false	在快照中包含示例数据行（CLI：--audit-backup-data）

提示： 开发时可调低 METADATA_CACHE_TTL_MS（例如 1000）；对于架构稳定的生产环境，可将其调高（例如 60000 = 1 分钟）。DDL 操作（CREATE/ALTER/DROP）会自动使架构缓存失效。

CLI 参考

db-mcp [options]

Transport:    --transport <stdio|http|sse>  --port <N>  --server-host <host>  --stateless
Auth:         --oauth-enabled --oauth-issuer <url> --oauth-audience <aud>
Database:     --sqlite <path>  |  --sqlite-native <path>  [--encryption-key <key>]
Extensions:   --csv  --spatialite                         (native only)
Security:     --allowed-io-roots <paths>
Audit:        --audit-log <path>  --audit-no-redact  --audit-reads  --audit-backup  --audit-backup-data
Server:       --name <name>  --version <ver>  --metrics-export <type>  --tool-filter <filter>

CLI 标志会覆盖环境变量。运行 node dist/cli.js --help 查看完整详情。

📚 MCP 客户端配置

添加到你的 ~/.cursor/mcp.json、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",
        "codemode"
      ]
    }
  }
}

提示

切换后端： 上述配置使用 Native 后端（better-sqlite3，181 个 MCP 工具）。若要使用 WASM 后端（sql.js，154 个 MCP 工具，无原生依赖），请在 args 数组中将 --sqlite-native 改为 --sqlite。有关功能差异，请参阅 DOCKER_README 中的后端选项表。

变体（修改上方的 args 数组）：

变体	修改
WASM 后端	将 --sqlite-native 替换为 --sqlite
内存数据库	将数据库路径替换为 :memory:
入门预设	将 "codemode" 替换为 "starter"，以便单独调用工具
CSV 扩展	在 "--tool-filter" 前添加 "--csv"（仅限 native）
SpatiaLite	添加 "--spatialite"，并设置 env: { "SPATIALITE_PATH": "/path/to/mod_spatialite" }（仅限 native）
Linux/macOS	使用正斜杠 Unix 路径（例如，/path/to/db-mcp/dist/cli.js）
Docker	将 "command": "node" 替换为 "command": "docker"，并将 args 包装在 run -i --rm -v ./data:/app/data writenotenow/db-mcp:latest 中

请参阅工具筛选，自定义要公开的工具。

🌐 HTTP/SSE 传输（远程访问）

若要远程访问、供 Web 客户端使用或连接兼容 HTTP 的 MCP 主机，请使用 HTTP 传输：

node dist/cli.js \
  --transport http \
  --port 3000 \
  --sqlite-native ./database.db \
  --allowed-io-roots $(pwd)

Docker：

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --transport http --port 3000 \
  --sqlite-native /app/data/database.db \
  --allowed-io-roots /app/data

此服务同时支持两种 MCP 传输协议，让现代客户端和旧版客户端都能连接：

Streamable HTTP（推荐）

现代协议（MCP 2025-03-26）——单一端点，基于会话：

方法	端点	用途
POST	/mcp	JSON-RPC 请求（initialize、tools/list 等）
GET	/mcp	用于服务通知的 SSE 流
DELETE	/mcp	终止会话

会话通过 Mcp-Session-Id 标头管理。

无状态模式

适用于无需会话的无服务器／无状态部署：

node dist/cli.js --transport http --port 3000 --stateless --sqlite-native ./database.db --allowed-io-roots $(pwd)

在无状态模式下：GET /mcp 返回 405，DELETE /mcp 返回 204，/sse 和 /messages 返回 404。每个 POST /mcp 都会创建一个新的传输。

旧版 SSE（向后兼容）

旧版协议（MCP 2024-11-05）——适用于 Python mcp.client.sse 等客户端：

方法	端点	用途
GET	/sse	打开 SSE 流，返回 /messages?sessionId=<id> 端点
POST	/messages?sessionId=<id>	向会话发送 JSON-RPC 消息

实用端点

方法	端点	用途
GET	/health	健康检查（绕过速率限制，始终可供监控使用）

🔐 身份验证

db-mcp 使用严格的 OAuth 2.1 身份验证来保护 HTTP 传输：

OAuth 2.1（企业版）

完整支持 OAuth 2.1，并符合 RFC 9728/8414，可用于生产环境中的多租户部署：

node dist/cli.js \
  --transport http \
  --port 3000 \
  --sqlite-native ./database.db \
  --allowed-io-roots $(pwd) \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/db-mcp \
  --oauth-audience db-mcp-server

其他标志： --oauth-jwks-uri <url>（如果省略则自动发现）、--oauth-clock-tolerance <seconds>（默认值：60）。

OAuth 作用域

通过 OAuth 作用域管理访问控制：

作用域	描述
full	不受限制地访问所有操作
read	对所有数据库进行只读访问
write	对所有数据库进行读写访问
admin	完整的管理访问权限

RFC 合规性

此实现遵循：

• RFC 9728 — OAuth 2.1 受保护资源元数据
• RFC 8414 — OAuth 2.1 授权服务器元数据
• RFC 7591 — OAuth 2.1 动态客户端注册

服务会在 /.well-known/oauth-protected-resource 提供元数据。

Keycloak 用户须知： 为客户端添加 Audience mapper（Client → Client scopes → dedicated scope → Add mapper → Audience），以便在令牌中包含正确的 aud 声明。

说明

按工具强制执行作用域： 作用域在工具级别强制执行 — 每个工具组都映射到所需的作用域（read、write 或 admin）。未知或未映射的工具默认需要 admin（失败时默认拒绝）。启用 OAuth 后，每次调用工具前都会检查调用令牌的作用域。未配置 OAuth 时，则完全跳过作用域检查。

提示

审计身份集成： 启用 OAuth 并同时启用审计日志记录（--audit-log）时，写入/管理工具的审计条目会自动记录经过身份验证的用户（claims.sub）和已授予的作用域。这样可以建立完整的取证记录，将每次变更关联到特定身份。未启用 OAuth 时，这些字段为 null/[]。

警告

未启用身份验证的 HTTP： 使用 --transport http 而未启用 OAuth 时，所有客户端都拥有不受限制的完整访问权限。生产环境中部署 HTTP 时，务必启用身份验证。详情请参阅 SECURITY.md。

🔐 静态加密（仅 Native）

db-mcp 通过 better-sqlite3-multiple-ciphers 驱动程序使用 SQLCipher，支持透明的数据库加密。启用加密后，服务会自动加密目标数据库（如果是新建数据库）和旁路 SystemDb 审计日志，确保静态存储的架构、查询和结果受到保护。

重要的 WASM 限制：WASM 后端（sql.js）不支持加密。如果向 WASM 后端提供加密密钥，它会正常忽略该密钥对目标数据库的影响。不过，如果 Native 和 WASM 后端共用同一个 --audit-log 文件，就可能发生冲突（Native 后端会加密共享的审计日志，导致 WASM 后端读取时崩溃）。为避免双后端设置中的此类问题，请为 WASM 实例指定单独的审计日志（例如 --audit-log mcp-audit-wasm.db）。

配置密钥： 你可以通过 --encryption-key CLI 标志或 DB_ENCRYPTION_KEY 环境变量提供密钥。

1. 强口令：标准字符串。SQLCipher 会自动使用 PBKDF2 派生密钥。

   DB_ENCRYPTION_KEY="your-strong-passphrase-here"
   

2. 原始十六进制密钥（性能最佳）：若要跳过 PBKDF2 派生开销，请提供精确的 256 位原始十六进制密钥，并在前面加上 x，再用单引号括起来：

   DB_ENCRYPTION_KEY="x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'"
   

警告

审计日志兼容性：DB_ENCRYPTION_KEY 环境变量会全局生效，并导致内部 SystemDb 尝试解密审计日志（--audit-log）。如果已有未加密的审计日志，服务将因 file is not a database 而无法启动。若只需加密目标数据库（让审计日志保持未加密），请改用 --encryption-key CLI 标志，而不要使用全局环境变量。

📊 基准测试

性能基准测试使用 Vitest bench（tinybench）测量关键热路径上的框架开销。该测试套件验证框架内部机制相较于实际数据库 I/O 的开销可以忽略不计：

• 工具分发： 6–14M 次操作/秒 — 基于 Map 的查找几乎没有成本
• 身份验证作用域检查： 4–8M 次操作/秒 — OAuth 中间件不会带来可测量的延迟
• 标识符验证： 4–7M 次操作/秒 — SQL 清理几乎瞬间完成
• 架构缓存命中： 3–6M 次操作/秒 — 元数据查找可避免冗余查询
• 调试日志（已过滤）： 5–11M 次操作/秒 — 禁用的日志级别确实不会产生任何开销
• Code Mode 安全性： 典型代码约 0.2–1.3M 次验证/秒，拦截的模式会在 1–2 µs 内被拒绝
• 沙盒执行： 约 0.5–4.9K 次执行/秒 — 简单代码经 V8 隔离区往返仅需 0.2–1.5 ms

pnpm run bench            # Run all benchmarks
pnpm run bench:verbose    # Verbose mode with detailed timings

基准测试	测量内容
处理器分发	工具查找、错误构造、进度通知开销
实用工具	标识符清理、WHERE 子句验证、SQL 验证
工具筛选	筛选器解析、分组查找、元分组目录生成
架构解析	简单、复杂、大型载荷的 Zod 架构验证，以及失败路径
日志记录与清理	日志调用开销、消息清理、敏感数据脱敏
传输与身份验证	令牌提取、作用域检查、错误格式化、速率限制
Code Mode	沙盒创建、池生命周期、安全验证、执行
数据库操作	PRAGMA 操作、表元数据、查询结果处理、架构缓存
资源与提示词	URI 匹配、内容组装、提示词生成、工具索引

---

贡献

欢迎贡献！提交拉取请求前，请阅读我们的贡献指南。

安全

有关安全问题，请参阅我们的安全策略。

⚠️ 切勿提交凭据 - 请将机密存储在 .env 中（已被 gitignore 忽略）

许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

行为准则

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