AI导哈

SQLite模型上下文协议服务器

一个支持全异步的SQLite模型上下文协议（MCP）服务器，为语言模型提供安全高效的SQLite数据库查询、分析和管理功能。

  • by LeoDev2p
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 LeoDev2p/mcp-sqlite

使用说明

MCP SQLite服务器

███╗   ███╗ ██████╗██████╗     ███████╗ ██████╗ ██╗     ██╗████████╗███████╗
████╗ ████║██╔════╝██╔══██╗    ██╔════╝██╔═══██╗██║     ██║╚══██╔══╝██╔════╝
██╔████╔██║██║     ██████╔╝    ███████╗██║   ██║██║     ██║   ██║   ███████╗
██║╚██╔╝██║██║     ██╔═══╝     ╚════██║██║   ██║██║     ██║   ██║   ██║════
██║ ╚═╝ ██║╚██████╗██║         ███████║╚██████╔╝███████╗██║   ██║   ███████║
╚═╝     ╚═╝ ╚═════╝╚═╝         ╚══════╝ ╚═════╝ ╚══════╝╚═╝   ╚═╝   ╚══════╝
                                V 0.2.0

专业人士 模型上下文协议（MCP） SQLite服务器 完全异步支持 它使语言模型能够安全有效地查询、分析和管理SQLite数据库。

概述

此MCP在语言模型（如Claude）和SQLite数据库之间提供了一个安全的、完全异步的接口。它能够：

  • 列出表格 在数据库中可用
  • 探索模式 表（列、数据类型）
  • 执行SQL查询 有充分准备的发言
  • 创建索引 优化性能
  • 高级异步日志记录 具有日志轮换和磁盘管理功能

需求

  • Python 3.12+
  • 紫外线 （超快包管理器）
  • SQLite 3.x（默认包含在Python中）
  • SQLite数据库（.db）

安装uv

视窗

  1. 打开 PowerShell 作为管理员
  2. 运行安装程序：
PowerShell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 重新启动终端

验证任何操作系统上的安装：

uv --version

项目安装

1.克隆存储库

git clone https://github.com/LeoDev2p/mcp-sqlite.git
cd mcp_sqlite

2.使用uv安装依赖项

uv sync

此命令：

  • 创建虚拟环境（.vnv）
  • 从安装依赖项 pyproject.toml
  • 自动配置FastMCP和MCP

3.验证安装

uv run server.py --help

如果一切正常，您应该看到MCP服务器帮助。

克劳德桌面和反重力配置

MCP服务器配置为 所有三个平台都相同 --只有配置文件的位置发生了变化。

配置文件位置

平台 文件位置
克劳德桌面版 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/.config/Claude/claude_desktop_config.json （macOS/Linux）
反重力 %APPDATA%\Antigravity\mcp_config.json （Windows）或 ~/.config/Antigravity/mcp_config.json （macOS/Linux）

安装说明

  1. 打开或创建 适合您平台的配置文件（见上表）

  2. 添加以下JSON配置 在...之内 mcpServers 章节：

{
  "mcpServers": {
    "sqlite": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\mcp_sqlite",
        "run",
        "python",
        "-m",
        "src.sqlite_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp_sqlite",
        "SQLITE_DB_PATH": "C:\\path\\to\\your\\database.db"
      }
    }
  }
}

平台特定路径示例：

  • 视窗: C:\\Users\\YourName\\path\\to\\database.db
  • macOS/Linux: /home/username/path/to/database.db
  1. 重新启动应用程序 （Claude Desktop或Antigravity）使更改生效
  2. SQLite工具将立即出现在工具菜单中

架构概述

异步优先设计

服务器完全由以下组件构建 async/await 最佳性能模式：

  • 异步连接池：用途 aiosqlite 用于非阻塞数据库访问
  • 并行工具执行：可以同时处理多个查询而不会阻塞
  • 资源管理：使用上下文管理器自动清理连接(async with)
  • 线程安全操作：内置支持来自语言模型的并发请求

数据库连接流

FastMCP Server (async)
    ↓
    async sqlite_connection() function
    ↓
    aiosqlite.connect() (non-blocking)
    ↓
    SQL Execution (prepared statements)
    ↓
    Response (cached or streamed)

� 工具参考

所有工具都是 完全异步 并使用预先准备好的声明来保证安全：

1. list_tables()

列出数据库中的所有表名。

类型： 异步读
克劳德的例子：

"What tables are available in the database?"

预期响应：

['movies', 'actors', 'genres', 'ratings']

2. get_table_schema(table_name: str)

返回特定表的列名和类型。

参数：

  • table_name （str）：要探索的表的名称

类型： 异步读
克劳德的例子：

"Show me the schema of the 'movies' table"

预期响应：

['id', 'title', 'year', 'director', 'rating']

3. execute_read_query(query: str, params: tuple = (), limit: int = 20)

使用准备好的语句安全地执行READ查询（SELECT、WITH/CTE、JOINS等）。

参数：

  • query （str）：有效的SQL SELECT或WITH查询
  • params （tuple）：占位符的值，以防止SQL注入（默认值：空）
  • limit （int）：返回的最大行数（默认值：20）

类型： 异步读
安全功能：

  • 准备好的语句可防止SQL注入
  • 自动限制保护防止数据过载
  • 仅支持SELECT和WITH查询
  • 执行前验证查询结构

克劳德的例子：

"Execute this query: SELECT title, year FROM movies WHERE year > ?"
With params: (2000,)

预期响应：

[('Inception', 2010), ('Interstellar', 2014), ('Oppenheimer', 2023)]

4. execute_write_query(query: str, params: tuple = ())

使用准备好的语句安全地执行WRITE查询（INSERT、UPDATE、DELETE）。

参数：

  • query （str）：有效的SQL INSERT、UPDATE或DELETE查询
  • params （tuple）：占位符的值，以防止SQL注入（默认值：空）

类型： 异步写入
安全功能：

  • 准备好的语句可防止SQL注入
  • 阻止在此处执行意外的SELECT查询
  • 自动提交交易
  • 全面的错误处理

克劳德的例子：

"Insert a new movie with title 'Avatar' and year 2022"
Query: INSERT INTO movies (title, year) VALUES (?, ?)
With params: ('Avatar', 2022)

预期响应：

"Write query executed successfully."

5. create_index(table_name: str, column_name: str)

在列上创建索引，以加快对大型表的搜索。

参数：

  • table_name （str）：表的名称
  • column_name （str）：要索引的列的名称

类型： 异步写入
性能影响： 显著加快了索引列上WHERE子句的过滤速度

克劳德的例子：

"Create an index on the 'movies' table for the 'year' column"

预期响应：

"Index idx_movies_year created successfully. Searches will now be faster."

安全特性

路径验证

if not os.path.exists(DB_PATH):
    return f"Error: File not found at {DB_PATH}"
  • 验证数据库文件是否存在
  • 防止配置错误

稳健的错误处理

try:
    # Query execution
except sqlite3.IntegrityError as e:
    return f"Error: {str(e)}"
except sqlite3.OperationalError as e:
    # Detailed logging for debugging
    log.error(f"SQL Error: {str(e)}")

环境变量

数据库路径是通过以下方式配置的 SQLITE_DB_PATH 而不是硬编码，改进：

  • 可移植性
  • 安全
  • 灵活性

记录系统

日志会自动保存到 logs/server.log 用于审计和调试。

想贡献吗？

看 贡献.md 有关以下内容的详细指南：

  • 添加具有适当模式的新异步工具
  • 改进测井系统
  • 修复错误和文档
  • 完成开发设置和PR流程

支持和故障排除

检查日志

所有活动都记录到 logs/server.log:

# View recent logs
tail -f logs/server.log

# On Windows PowerShell
Get-Content logs/server.log -Tail 20 -Wait

常见问题

问题： SQLITE_DB_PATH not found
解决方案： 验证路径是否正确以及数据库文件是否存在

问题： 查询速度慢
解决方案： 使用 create_index() 在频繁搜索的列上

问题： “连接被拒绝”
解决方案： 确保配置更改后重新启动Claude Desktop

版本： 0.2.0
上次更新时间： 2026-04-21

相关 MCP