AI导哈

SQLite MCP服务器

一个用于SQLite的模型上下文协议（MCP）服务器，支持临时内存数据库和持久化数据库，提供数据库生命周期管理、查询/执行操作、批量写入、数据导入和游标分页等功能。

  • by bradsjm
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 bradsjm/sqlite-mcp-rs

使用说明

sqlite-mcp-rs

SQLite的有界模型上下文协议（MCP）服务器，具有stdio（默认）和可选的HTTP传输。它支持临时内存数据库和持久数据库，并为数据库生命周期、查询/执行操作、批写入、数据导入、基于光标的分页和可选的向量搜索提供类型化工具。

特性

  • 有界SQL执行：对语句长度、行数和响应字节有严格限制
  • 默认安全策略：块 ATTACH 和 LOAD_EXTENSION，确认破坏性批量操作
  • 类型化MCP合同：结构化的请求/响应模式和一致的工具包
  • 光标分页：可恢复 sql_query 具有TTL和有限的光标容量
  • 短暂+持续支持：在内存中打开/列出/关闭（临时）和文件支持（持久）SQLite数据库
  • 进口支持：将CSV或JSON行摄取到已验证的表/列目标中
  • 轻量级队列原语：通过MCP/HTTP推送JSON作业并对新行进行长轮询
  • 可选矢量搜索：具有嵌入和可选重新排序功能的sqlite-vec集合(vector 特征）

安装

根据您的环境选择以下选项之一。

使用NPX

如果这个包发布到npm：

npx @bradsjm/sqlite-mcp-rs@latest

或全局安装：

npm install -g @bradsjm/sqlite-mcp-rs
sqlite-mcp-rs

使用Docker

具有最新映像的本地stdio传输：

docker run --rm -i --env-file .env ghcr.io/bradsjm/sqlite-mcp-rs:latest

已发布的Docker镜像使用glibc运行时，并包括本地嵌入/重新排序支持。

通过HTTP传输运行：

docker run --rm -i --env-file .env ghcr.io/bradsjm/sqlite-mcp-rs:latest -- --transport http --host localhost --port 3000

本地构建：

docker build -t sqlite-mcp-rs .
docker run --rm -i --env-file .env sqlite-mcp-rs

来源

cargo install --path .

或者直接运行：

cargo run

通过HTTP传输运行：

cargo run -- --transport http --host localhost --port 3000

快速开始

配置MCP

使用此MCP配置模板并设置 optional 持久化数据库的环境值。

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@bradsjm/sqlite-mcp-rs@latest"],
      "env": {
        "SQLITE_PERSIST_ROOT": "/absolute/path/to/sqlite-data",
      }
    }
  }
}

运输选项

服务器支持：

  • --transport stdio （默认）
  • --transport http --host localhost --port 3000

启用HTTP传输后，暴露并连接到：

http://<host>:<port>/mcp

HTTP连接不是按数据库句柄的会话隔离的。一个服务器进程中的所有HTTP客户端共享相同的 SQLITE_PERSIST_ROOT 以及相同的进程内注册表，因此它们可以同时打开和使用相同的持久数据库文件。

核心环境变量

默认值如下所示。

SQLITE_PERSIST_ROOT=                       # optional; if unset, only ephemeral (memory) databases are allowed
SQLITE_LOG_LEVEL=info
SQLITE_MAX_SQL_LENGTH=20000
SQLITE_MAX_STATEMENTS=50
SQLITE_MAX_ROWS=100
SQLITE_MAX_BYTES=65536
SQLITE_MAX_DB_BYTES=100000000
SQLITE_MAX_PERSISTED_LIST_ENTRIES=500
SQLITE_CURSOR_TTL_SECONDS=600
SQLITE_CURSOR_CAPACITY=500
SQLITE_QUEUE_WAIT_TIMEOUT_MS_DEFAULT=30000
SQLITE_QUEUE_WAIT_TIMEOUT_MS_MAX=120000
SQLITE_QUEUE_POLL_INTERVAL_MS_DEFAULT=250
SQLITE_QUEUE_POLL_INTERVAL_MS_MIN=50
SQLITE_QUEUE_POLL_INTERVAL_MS_MAX=5000

矢量特征（可选）

使用矢量集合支持构建/运行：

cargo run --features vector

添加本地嵌入；仅在需要时配置重新银行：

cargo run --features "vector local-embeddings"

矢量环境变量：

SQLITE_VECTOR_DIMENSION=384
SQLITE_MAX_VECTOR_TOP_K=200
SQLITE_MAX_RERANK_FETCH_K=500

本地嵌入环境变量(local-embeddings 仅功能）： 重新排名是选择加入：全部留下 SQLITE_RERANKER_* 按键为空可禁用它。

SQLITE_EMBEDDING_PROVIDER=fastembed
SQLITE_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
SQLITE_EMBEDDING_CACHE_DIR=                # optional
SQLITE_RERANKER_PROVIDER=                  # leave empty to keep reranking disabled
SQLITE_RERANKER_MODEL=                     # leave empty to keep reranking disabled
SQLITE_RERANKER_CACHE_DIR=                 # optional

工具参考

所有工具都返回一个一致的信封：

{
  "summary": "Human-readable outcome",
  "data": {},
  "_meta": {
    "now_utc": "2026-03-02T00:00:00Z"
  }
}

数据库工具

工具 目的
db_open 打开并激活内存或持久化数据库句柄
db_list 列出活动/打开的句柄和发现的持久数据库
db_close 关闭数据库句柄并使相关游标无效

SQL工具

工具 目的
sql_query 执行一条具有有界结果和可选游标连续性的只读语句
sql_execute 执行一条非读取语句并返回写入元数据
sql_batch 使用可选事务和破坏性保护执行多个写语句
db_import 将CSV/JSON行导入表中

队列工具

工具 目的
queue_push 将JSON作业插入到命名队列中
queue_wait 在呼叫者基线后对下一个可见作业进行长时间轮询

矢量工具(vector 特征）

工具 目的
vector_status 检查矢量运行准备情况，并可选择预热模型
vector_collection_create 创建矢量集合支持表
vector_collection_list 列出矢量集合和元数据
vector_upsert 插入嵌入式矢量文档
vector_search 运行语义KNN搜索，可选择重新排序

有关完整的模式和验证规则，请参阅 docs/tool-contract.md.

政策和安全

  • sql_query 只接受一条只读语句。
  • sql_execute 和 sql_batch 拒绝阅读声明。
  • ATTACH 和 LOAD_EXTENSION 被封锁。
  • 破坏性批量写入需要 confirm_destructive=true.
  • 写入内部表 _vector_collections 被阻止使用通用SQL工具。
  • queue_wait 默认为 include_existing=false 因此，除非呼叫者选择加入，否则他们会等待新行。

故障排除

持久模式被拒绝

如果 db_open 与 mode="persist" 失败，确保 SQLITE_PERSIST_ROOT 已设置。

查询被策略阻止

如果您看到被阻止的SQL错误，请删除 ATTACH / LOAD_EXTENSION 或使用允许的语句。

批次因破坏性而被拒收

对于 DROP, TRUNCATE，或 DELETE 没有 WHERE，set confirm_destructive=true.

矢量工具不可用

与一起跑步 --features vector 用于收集支持，以及 --features "vector local-embeddings" 用于本地嵌入/重新排序。Linux GNU npm有效负载包括本地嵌入/重新排序，需要glibc 2.28或更高版本；Linux musl版本和npm有效载荷仍然只是矢量。

发展

运行单元测试：

cargo test

对MCP检查器运行集成检查：

bash scripts/test-sqlite-mcp-inspector.sh cargo run --

通过HTTP传输对MCP检查器运行集成检查：

bash scripts/test-sqlite-mcp-inspector-http.sh cargo run --

stdio脚本默认为 SQLITE_INSPECTOR_VECTOR_MODE=disabled，其中 断言向量工具不存在。使用 degraded 测试a vector 建造 无需下载模型：

SQLITE_INSPECTOR_VECTOR_MODE=degraded \
  bash scripts/test-sqlite-mcp-inspector.sh cargo run --features vector --

使用 local 对于真正的FastEmbed嵌入和重新排序流程：

SQLITE_INSPECTOR_VECTOR_MODE=local \
  bash scripts/test-sqlite-mcp-inspector.sh cargo run --features local-embeddings --

拉取请求并推送至 main 在中运行确定性Rust和MCP矩阵 .github/workflows/integration.yml依赖于网络的真实模型流运行 每周或按需通过 .github/workflows/model-integration.yml.

显示CLI帮助：

sqlite-mcp-rs --help

相关 MCP