Sqlite MCP Server

🚀 SQLite MCP 服务器

企业级 SQLite，具备原生 AI 的 JSON 操作和智能工作流自动化功能 – v2.6.4

将 SQLite 转变为强大的、适配 AI 的数据库引擎，拥有 73 种专业工具，可用于高级分析、JSON 操作、文本处理、向量搜索、地理空间操作和智能工作流自动化。

Wiki • 更新日志 • 发布文章

---

📋 目录

快速开始

• ✅ 快速测试 - 验证一切正常工作
• 🚀 快速启动
• 🔥 核心功能
• 🏢 企业级特性

配置与使用

• 📚 MCP 客户端配置
• 🎛️ 工具过滤
• 🎨 使用示例
• 📊 工具类别

资源与信息

• 🏆 为何选择 SQLite MCP 服务器？
• 🔍 人工智能驱动的维基搜索
• 📚 完整文档
• 👏 贡献者
• 🔗 额外资源
• 🚀 快速链接
• 📈 项目统计

---

✅ 快速测试 - 验证一切正常工作

30 秒内测试全部 73 个工具！

快速冒烟测试：

python test_runner.py --quick

标准综合测试（推荐）：

python test_runner.py --standard

包含边界情况的完整测试套件：

python test_runner.py --full

预期输出：

🚀 SQLite MCP 服务器综合测试套件 v2.6.4
================================================================

🔍 环境检测：
  ✅ SQLite 3.50.4（支持 JSONB）
  ✅ Python 3.13.x  
  ✅ MCP 1.14.0
  ✅ Pyright 严格类型检查：通过

📊 测试 14 个类别中的 73 个工具...

✅ 核心数据库操作（8/8 通过）
✅ JSON 辅助工具（6/6 通过）  
✅ JSON 操作（12/12 通过）  
✅ 文本处理（8/8 通过）
🎉 成功：所有 73 个工具测试成功！

🛡️ 安全测试

新增：全面的 SQL 注入防护测试

测试 SQL 注入防护（从 tests 目录）：

cd tests && python test_sql_injection.py

预期结果：🛡️ 整体安全态势：强

测试内容：

• 防范原始 Anthropic SQLite MCP 服务器中发现的 SQL 注入漏洞
• 11 种不同的攻击向量，包括多语句、UNION 注入、盲注
• 带有恶意负载的参数绑定防护
• 堆叠查询和基于注释的注入尝试

⬆️ 返回目录

🚀 快速启动

选项 1：Docker（推荐）

立即拉取并运行：

docker pull writenotenow/sqlite-mcp-server:latest

使用卷挂载运行：

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

🛡️ 供应链安全

为增强安全性和实现可重现构建，请使用 SHA 固定的镜像：

可在以下地址查找可用的 SHA 标签：https://hub.docker.com/r/writenotenow/sqlite-mcp-server/tags 查找以 "master-" 或 "sha256-" 开头的标签，以获取经过加密验证的构建

选项 1：人类可读的带时间戳的构建（推荐）

docker pull writenotenow/sqlite-mcp-server:master-YYYYMMDD-HHMMSS-<commit>

选项 2：多架构清单摘要（最高安全性）

docker pull writenotenow/sqlite-mcp-server@sha256:<manifest-digest>

示例：使用经过加密验证的镜像运行

docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:master-YYYYMMDD-HHMMSS-<commit> \
  --db-path /workspace/database.db

如何查找 SHA 标签：

1. 访问 Docker Hub 标签
2. 为方便起见：使用 master-YYYYMMDD-HHMMSS-<commit> 标签（人类可读、多架构）
3. 为实现最高安全性：使用 sha256-<manifest-digest> 标签（多架构清单摘要，适用于所有架构）

SHA 标签说明：

• 🏷️ master-YYYYMMDD-HHMMSS-<commit> - 人类可读、带时间戳、多架构安全
• 🔒 sha256-<manifest-digest> - 多架构清单摘要（适用于所有架构）
• ⚠️ 特定架构的摘要 - 仅用于调试特定架构

安全特性：

• ✅ 构建来源 - 构建过程的加密证明
• ✅ SBOM 可用 - 完整的软件物料清单
• ✅ 供应链认证 - 可验证的构建完整性
• ✅ 可重现构建 - 精确的镜像验证以确保合规性

选项 2：Python 安装

从 PyPI 安装：

pip install sqlite-mcp-server-enhanced

或从源代码安装：

git clone https://github.com/neverinfamous/sqlite-mcp-server.git

进入目录：

cd sqlite-mcp-server

安装依赖：

pip install -r requirements.txt

运行服务器：

python start_sqlite_mcp.py --db-path ./database.db

选项 3：30 秒内测试

克隆仓库：

git clone https://github.com/neverinfamous/sqlite-mcp-server.git

进入目录：

cd sqlite-mcp-server

运行快速测试：

python test_runner.py --quick

🆕 v2.6.4 新增功能：工具过滤

通过 SQLITE_MCP_TOOL_FILTER 环境变量选择性启用/禁用工具：

• 解决 MCP 客户端工具限制问题（Windsurf 的 100 个工具限制、Cursor 稳定性问题）
• 仅暴露所需工具，减少令牌开销
• 基于组的过滤（-vector、-stats）和单个工具控制（+vacuum_database）

完整文档请参阅 工具过滤。

v2.6.0：完整的 JSON 操作套件

此版本的 5 大改进：

• 🎯 JSON 辅助工具 - 6 个专门的工具，用于简化 JSON 操作，具备路径验证和合并功能
• 🤖 JSON 自动规范化 - 自动修复 Python 风格的 JSON，支持可配置的严格模式
• 🛡️ 参数绑定接口 - 增强 MCP 工具，具备 SQL 注入防护功能
• 📦 自动参数序列化 - 直接使用对象/数组参数，无需手动调用 JSON.stringify()
• 🧠 增强的 JSON 错误诊断 - 智能错误分类，提供上下文指导

---

⚡ 安装到 Cursor IDE

一键安装

点击下面的按钮直接安装到 Cursor：

或者复制此深度链接：

cursor://anysphere.cursor-deeplink/mcp/install?name=SQLite%20MCP%20Server&config=eyJzcWxpdGUtbWNwIjp7ImFyZ3MiOlsicnVuIiwiLWkiLCItLXJtIiwiLXYiLCIkKHB3ZCk6L3dvcmtzcGFjZSIsIndyaXRlbm90ZW5vdy9zcWxpdGUtbWNwLXNlcnZlcjpsYXRlc3QiLCItLWRiLXBhdGgiLCIvd29ya3NwYWNlL3NxbGl0ZV9tY3AuZGIiXSwiY29tbWFuZCI6ImRvY2tlciJ9fQ==

先决条件

• ✅ 已安装并运行 Docker
• ✅ 可用磁盘空间约 500MB

配置

安装后，Cursor 将使用基于 Docker 的此配置：

{
  "sqlite-mcp": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "$(pwd):/workspace",
      "writenotenow/sqlite-mcp-server:latest",
      "--db-path", "/workspace/sqlite_mcp.db"
    ]
  }
}

📖 查看完整安装指南 →

---

🔥 核心功能

• 📊 统计分析 - 描述性统计、百分位数、时间序列分析
• 🔍 高级文本处理 - 正则表达式、模糊匹配、语音搜索、相似度计算
• 🧠 向量/语义搜索 - 原生 AI 嵌入、余弦相似度、混合搜索
• 🗺️ SpatiaLite 地理空间 - 企业级 GIS，具备空间索引和操作功能
• 🔐 事务安全 - 自动包装事务，具备回滚保护功能
• 🎛️ 73 个专业工具 - 完整的数据库管理和分析套件

🏢 企业级特性

• 📈 商业智能 - 集成洞察备忘录和工作流自动化功能
• 🔄 备份/恢复 - 企业级操作，具备完整性验证功能
• 🎯 全文搜索 (FTS5) - 高级搜索，具备 BM25 排名和摘要功能
• 🏗️ 虚拟表 - 智能 CSV/JSON 导入，具备自动类型推断功能
• ⚙️ 高级 PRAGMA - 完整的 SQLite 配置和优化功能

⬆️ 返回目录

📚 MCP 客户端配置

Claude Desktop

{
  "mcpServers": {
    "sqlite-mcp-server": {
      "command": "python",
      "args": ["/path/to/sqlite-mcp-server/start_sqlite_mcp.py", "--db-path", "/path/to/database.db"]
    }
  }
}

使用 Claude Desktop 的 Docker

{
  "mcpServers": {
    "sqlite-mcp-server": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/path/to/project:/workspace", "writenotenow/sqlite-mcp-server:latest", "--db-path", "/workspace/database.db"]
    }
  }
}

⬆️ 返回目录

🎛️ 工具过滤

v2.6.4 新增功能

一些 MCP 客户端存在工具限制（例如，Windsurf 的 100 个工具限制）。使用 SQLITE_MCP_TOOL_FILTER 环境变量仅暴露所需的工具。

过滤语法

语法	描述
-group	禁用组中的所有工具
-tool	禁用特定工具
+tool	重新启用工具（在禁用组后很有用）

规则按从左到右的顺序处理，因此顺序很重要。

可用组

组	工具数量	描述
core	5	基本的 CRUD 操作：read_query、write_query、create_table、list_tables、describe_table
fts	4	全文搜索：fts_search、create_fts_table、rebuild_fts_index、hybrid_search
vector	11	语义/向量搜索和嵌入
json	9	JSON 操作和验证
virtual	8	虚拟表：CSV、R-Tree、series
spatial	7	SpatiaLite 地理空间操作
text	7	文本处理：模糊匹配、语音搜索、正则表达式
stats	8	统计分析
admin	14	数据库管理和 PRAGMA 操作
misc	5	杂项实用工具

配置示例

使用 uvx（Cursor/Windsurf）：

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/neverinfamous/sqlite-mcp-server.git",
        "mcp-server-sqlite", "--db-path", "/path/to/database.db"
      ],
      "env": {
        "SQLITE_MCP_TOOL_FILTER": "-vector,-stats,-spatial,-text"
      }
    }
  }
}

使用 Docker：

{
  "mcpServers": {
    "sqlite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SQLITE_MCP_TOOL_FILTER=-vector,-stats,-spatial,-text",
        "-v", "/path/to/project:/workspace",
        "writenotenow/sqlite-mcp-server:latest",
        "--db-path", "/workspace/database.db"
      ]
    }
  }
}

常见配置

减少到约 50 个工具（与 Windsurf 兼容）：

SQLITE_MCP_TOOL_FILTER="-vector,-stats,-spatial,-text"

仅使用核心 + JSON 工具（最小占用空间）：

SQLITE_MCP_TOOL_FILTER="-fts,-vector,-virtual,-spatial,-text,-stats,-admin,-misc"

禁用管理工具，但保留 vacuum 和 backup 工具：

SQLITE_MCP_TOOL_FILTER="-admin,+vacuum_database,+backup_database"

只读模式（禁用写操作）：

SQLITE_MCP_TOOL_FILTER="-write_query,-create_table"

⬆️ 返回目录

🎨 使用示例

数据分析工作流

1. 快速验证：

python test_runner.py --quick

2. 开始处理数据：

python start_sqlite_mcp.py --db-path ./sales_data.db

3. 与 Claude/Cursor 一起使用，可进行以下操作：
   • 数据集的统计分析
   • 文本处理和模式提取
   • 向量相似度搜索
   • 地理空间分析和绘图
   • 商业智能洞察

Docker 开发

使用实时重新加载进行开发：

docker run -i --rm \
  -v $(pwd):/workspace \
  -e SQLITE_DEBUG=true \
  writenotenow/sqlite-mcp-server:latest \
  --db-path /workspace/dev.db

🎯 JSON 辅助工具 - 简化 JSON 操作

v2.6.0 新增功能： 六个强大的 JSON 辅助工具，使复杂的 JSON 操作变得简单：

// ✅ 插入 JSON 并自动规范化
json_insert({
  "table": "products",
  "column": "metadata", 
  "data": {'name': 'Product', 'active': True, 'price': None}
})

// ✅ 按路径更新 JSON
json_update({
  "table": "products",
  "column": "metadata",
  "path": "$.price",
  "value": 29.99,
  "where_clause": "id = 1"
})

// ✅ 使用复杂过滤查询 JSON
json_query({
  "table": "products",
  "column": "metadata",
  "filter_paths": {"$.category": "electronics"},
  "select_paths": ["$.name", "$.price"]
})

JSON 辅助工具：

• 🎯 json_insert - 插入 JSON 数据并自动规范化
• 🔄 json_update - 按路径更新 JSON，支持创建操作
• 🔍 json_select - 提取 JSON 数据，支持多种输出格式
• 🔎 json_query - 复杂的 JSON 过滤和聚合操作
• ✅ json_validate_path - 验证 JSON 路径，具备安全检查功能
• 🔗 json_merge - 合并 JSON 对象，具备冲突解决功能

自动规范化仍然有效：

• 🔧 单引号 → 双引号
• 🔧 Python 的 True/False → JSON 的 true/false
• 🔧 Python 的 None → JSON 的 null
• 🔧 去除尾随逗号
• 🛡️ 安全验证可防止恶意输入

🧠 增强的 JSON 错误诊断

v2.6.0 增强功能： 当 JSON 验证失败时，获取智能的、上下文相关的错误消息，并提供具体指导：

// ❌ 无效的 JSON 输入：
validate_json('{key_without_quotes: "value"}')

// ✅ 增强的错误响应：
{
  "valid": false,
  "error": "Expecting property name enclosed in double quotes: line 1 column 2 (char 1)",
  "enhanced_message": "JSON 验证失败 (结构语法错误): 期望属性名用双引号括起来...",
  "error_context": {
    "error_type": "structural_syntax",
    "security_concern": false,
    "suggestions": [
      "确保所有对象键都是正确引用的字符串",
      "检查键和值之间是否缺少冒号 (:)",
      "验证正确的键值对结构: \"key\": \"value\""
    ]
  }
}

增强的错误类别：

• 🔧 结构问题 - 缺少引号、冒号、括号，并提供具体的修复建议
• 🛡️ 安全警告 - 检测 JSON 字符串中潜在的 SQL 注入模式
• 📝 编码问题 - 字符编码和转义序列指导
• 🎯 上下文感知提示 - 提供行/列位置，并给出针对性的建议

🛡️ 增强的参数绑定 + 自动序列化

v2.6.0 新增功能： 内置 SQL 注入防护，支持自动 JSON 序列化：

// ✅ 安全：参数绑定可防止注入
read_query({
  "query": "SELECT * FROM users WHERE name = ? AND age > ?",
  "params": ["John", 25]
})

// ✅ 新增：直接使用对象/数组参数（自动序列化）
write_query({
  "query": "INSERT INTO products (metadata, tags) VALUES (?, ?)",
  "params": [
    {"name": "Product", "price": 29.99, "active": true},  // 自动序列化为 JSON
    ["electronics", "featured", "new"]                    // 自动序列化为 JSON
  ]
})

// ✅ 简化：无需手动调用 JSON.stringify()
// v2.6.0 之前：
write_query({
  "query": "INSERT INTO table (data) VALUES (?)",
  "params": [JSON.stringify({"key": "value"})]  // 需要手动序列化
})

// v2.6.0 之后：
write_query({
  "query": "INSERT INTO table (data) VALUES (?)",
  "params": [{"key": "value"}]  // 自动序列化！
})

v2.6.0 的优势：

• 🛡️ SQL 注入防护 - 参数绑定将恶意输入视为字面数据
• 📦 自动序列化 - 对象和数组自动转换为 JSON 字符串
• 🔄 向后兼容 - 现有查询继续正常工作
• ⚡ 更好的性能 - 查询计划缓存和参数优化
• 📝 更简洁的 API - 无需手动调用 JSON.stringify() 或进行参数准备

⬆️ 返回目录

📊 工具类别

SQLite MCP 服务器提供 14 个类别中的 73 个专业工具：

💡 想要完整的工具列表？ 请参阅 详细工具参考，其中包含所有 73 个工具、7 个资源和 7 个提示的描述。

类别	工具数量	描述
核心数据库	15	CRUD 操作、模式管理、事务处理
JSON 辅助工具	6	简化的 JSON 操作、路径验证、合并
文本处理	9	正则表达式、模糊匹配、语音搜索、相似度计算
统计分析	8	描述性统计、百分位数、时间序列
虚拟表	8	CSV、R-Tree、系列生成
语义搜索	8	嵌入、相似度、混合搜索
地理空间	7	空间索引、几何操作
PRAGMA 操作	5	配置、优化、自省
全文搜索	3	FTS5 创建、索引、BM25 排名
向量优化	2	ANN 搜索、聚类、性能优化
数据分析	2	智能 CSV/JSON 导入，具备类型推断功能
资源	7	数据库元感知、性能洞察
提示	7	引导式工作流、优化方案

💡 Cursor 用户： 您可以在 MCP 客户端设置中仅启用所需的类别，以减少工具干扰并提高稳定性。上面的每个数字表示该类别中的工具数量。

⬆️ 返回目录

🏆 为何选择 SQLite MCP 服务器？

✅ 对 AI 友好 - JSON 自动规范化和智能错误消息可减少调试时间
✅ 即插即用 - 内置安全功能和参数绑定，无需配置
✅ 智能诊断 - 增强的错误上下文在出现问题时提供可操作的指导
✅ 类型安全 - 在 Cursor 中通过严格的 Pyright 类型检查，确保最高代码质量
✅ 即时测试 - 30 秒内验证所有 73 个工具
✅ 生产就绪 - 经过企业级测试和验证
✅ 功能全面 - 一站式满足所有需求
✅ 支持 Docker - 容器化部署，轻松便捷
✅ 零破坏性更改 - 所有现有代码继续正常工作

⬆️ 返回目录

🔍 人工智能驱动的维基搜索

→ 使用人工智能搜索文档

找不到所需内容？使用我们的人工智能驱动的搜索界面搜索 SQLite 和 PostgreSQL MCP 服务器文档：

• 🤖 自然语言查询 - 用普通英语提问，获取人工智能生成的答案
• ⚡ 即时结果 - 人工智能增强的答案，附带来自两个维基的来源引用
• 📚 全面覆盖 - 搜索所有 73 个 SQLite 工具 + 63 个 PostgreSQL 工具（共 136 个）
• 🎯 智能上下文 - 理解技术问题并提供相关示例
• 🔄 双搜索模式 - 人工智能增强模式提供综合答案，原始文档模式提供直接内容

示例查询：

• "如何防止 SQL 注入攻击？"
• "有哪些统计分析工具可用？"
• "如何使用嵌入进行向量搜索？"
• "如何使用 JSON 辅助工具进行数据规范化？"
• "有哪些 SpatiaLite 地理空间操作可用？"

→ 立即尝试人工智能搜索

搜索界面使用 Cloudflare 的人工智能搜索技术，从 SQLite 和 PostgreSQL MCP 服务器的全面维基文档中提供智能、上下文相关的答案。

⬆️ 返回目录

📚 完整文档

→ 维基：全面的文档和示例

全面的文档包括：

• 详细的工具参考 - 所有 73 个工具的示例
• 高级配置 - 性能调优和优化
• 集成指南 - MCP 客户端、Docker、CI/CD
• 功能深入介绍 - 文本处理、向量搜索、地理空间
• 最佳实践 - 查询模式、故障排除、工作流
• API 参考 - 完整的工具架构和参数

📰 阅读 v2.6.0 版本发布文章 - 了解 JSON 操作、自动规范化和增强的安全性

→ GitHub Gists：实用示例和用例

9 个精心策划的 Gist，包含实际示例：

• JSON 辅助工具 - 简化的 JSON 操作和自动规范化
• 向量/语义搜索 - 原生 AI 嵌入和相似度搜索
• SpatiaLite GIS - 地理空间操作和空间索引
• 性能优化 - 查询调优和索引建议
• 安全最佳实践 - SQL 注入防护和安全查询
• 实际用例 - 商业智能和数据分析工作流
• 数据库迁移 - 模式演变和数据转换
• Docker 部署 - 生产容器化策略
• 完整功能展示 - 所有 73 个工具的综合示例

⬆️ 返回目录

👏 贡献者

特别感谢以下贡献者，他们帮助改进了 SQLite MCP 服务器：

v2.6.4 - 工具过滤功能

• @Insighttful - 实现了工具过滤系统 (PR #50)
  • 添加了 SQLITE_MCP_TOOL_FILTER 环境变量
  • 创建了 10 个逻辑工具组，实现灵活过滤
  • 贡献了全面的测试套件（410 行）
  • 解决了 MCP 客户端工具限制问题（Windsurf、Cursor）

想要贡献代码？请参阅我们的 贡献指南 开始！

⬆️ 返回目录

🔗 额外资源

• 测试指南 - 全面的测试文档
• 贡献说明 - 如何为项目做出贡献
• 安全策略 - 安全指南和报告流程
• 行为准则 - 社区准则
• 更新日志 - 版本历史和发布说明
• Docker Hub - 容器镜像
• GitHub 发布 - 版本下载
• Adamic 支持博客 - 项目公告和发布信息

⬆️ 返回目录

🚀 快速链接

操作	命令
人工智能驱动的搜索	search.adamic.tech
测试所有功能	python test_runner.py --standard
Docker 快速启动	docker run -i --rm -v $(pwd):/workspace writenotenow/sqlite-mcp-server:latest
从 PyPI 安装	pip install sqlite-mcp-server-enhanced
查看完整文档	docs/sqlite-mcp-server.wiki
报告问题	GitHub 问题

⬆️ 返回目录

📈 项目统计

• 73 个工具，分布在 14 个类别中（全部经过测试和验证 ✅）
• 2000 多行 全面的文档
• 多平台支持（Windows、Linux、macOS）
• 支持 amd64 和 arm64 的 Docker 镜像
• 通过 Pyright 严格类型检查，确保代码质量
• 经过企业级测试，具备全面验证
• 积极开发，定期更新

⬆️ 返回目录