金大哥 - sqlite-mcp-server MCP 详情

article

README

🚀 SQLite MCP 服务器

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

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

Wiki • 更新日志 • 发布文章

📋 目录

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

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 标签：

访问 Docker Hub 标签
为方便起见：使用 master-YYYYMMDD-HHMMSS-<commit> 标签（人类可读、多架构）
为实现最高安全性：使用 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"

⬆️ 返回目录

🎨 使用示例

数据分析工作流

快速验证：

python test_runner.py --quick

开始处理数据：

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

与 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 严格类型检查，确保代码质量
经过企业级测试，具备全面验证
积极开发，定期更新

⬆️ 返回目录

sqlite-mcp-server

README

🚀 SQLite MCP 服务器

📋 目录

快速开始

配置与使用

资源与信息

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

🛡️ 安全测试

🚀 快速启动

选项 1：Docker（推荐）

🛡️ 供应链安全

选项 2：Python 安装

选项 3：30 秒内测试

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

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

⚡ 安装到 Cursor IDE

一键安装

先决条件

配置

🔥 核心功能

🏢 企业级特性

📚 MCP 客户端配置

Claude Desktop

使用 Claude Desktop 的 Docker

🎛️ 工具过滤

过滤语法

可用组

配置示例

常见配置

🎨 使用示例

数据分析工作流

Docker 开发

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

🧠 增强的 JSON 错误诊断

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

📊 工具类别

🏆 为何选择 SQLite MCP 服务器？

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

📚 完整文档

👏 贡献者

v2.6.4 - 工具过滤功能

🔗 额外资源

🚀 快速链接

📈 项目统计

运行方式说明

托管运行

本地运行 / 其它方式