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 環境變量僅暴露所需的工具。

過濾語法

規則按從左到右的順序處理，因此順序很重要。

可用組

配置示例

使用 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 個提示的描述。

💡 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 支持博客 - 項目公告和發佈信息

⬆️ 返回目錄

🚀 快速鏈接

⬆️ 返回目錄

📈 項目統計

• 73 個工具，分佈在 14 個類別中（全部經過測試和驗證 ✅）
• 2000 多行 全面的文檔
• 多平臺支持（Windows、Linux、macOS）
• 支持 amd64 和 arm64 的 Docker 鏡像
• 通過 Pyright 嚴格類型檢查，確保代碼質量
• 經過企業級測試，具備全面驗證
• 積極開發，定期更新

⬆️ 返回目錄