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配置模板并设置 可选的 持久化数据库的环境值。
{
"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://:
/mcpHTTP连接不是按数据库句柄的会话隔离的。一个服务器进程中的所有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=500
SQLITE_MAX_BYTES=1048576
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_EMBEDDING_PROVIDER=fastembed
SQLITE_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
SQLITE_EMBEDDING_CACHE_DIR= # optional
SQLITE_RERANKER_PROVIDER=fastembed # optional (only if reranker enabled)
SQLITE_RERANKER_MODEL=BAAI/bge-reranker-base # optional (only if reranker enabled)
SQLITE_RERANKER_CACHE_DIR= # optional工具参考
所有工具都返回一个一致的信封：
{
"summary": "Human-readable outcome",
"data": {},
"_meta": {
"now_utc": "2026-03-02T00:00:00Z",
"elapsed_ms": 12,
"request_id": "uuid-v4"
}
}数据库工具
| 工具 | 目的 |
|---|---|
db_open | 打开并激活内存或持久化数据库句柄 |
db_list | 列出活动/打开的句柄和发现的持久数据库 |
db_close | 关闭数据库句柄并使相关游标无效 |
SQL工具
| 工具 | 目的 |
|---|---|
sql_query | 执行一条具有有界结果和可选游标连续性的只读语句 |
sql_execute | 执行一条非读取语句并返回写入元数据 |
sql_batch | 使用可选事务和破坏性保护执行多个写语句 |
db_import | 将CSV/JSON行导入表中 |
队列工具
| 工具 | 目的 |
|---|---|
queue_push | 将JSON作业插入到命名队列中 |
queue_wait | 在呼叫者基线后对下一个可见作业进行长时间轮询 |
矢量工具(vector 特征）
| 工具 | 目的 |
|---|---|
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 musl发布二进制文件和npm Linux包除外 local-embeddings.
发展
运行单元测试：
cargo test对MCP检查器运行集成检查：
bash scripts/test-sqlite-mcp-inspector.sh cargo run --通过HTTP传输对MCP检查器运行集成检查：
bash scripts/test-sqlite-mcp-inspector-http.sh cargo run --显示CLI帮助：
sqlite-mcp-rs --help