SQLite MCP 服务器
一个基于Python实现的SQLite标准MCP（Model Context Protocol）服务器，支持数据库的读写操作，使用Docker进行容器化部署，以stdio模式运行，支持自然语言交互。
功能特性
- 🔍 SQL查询执行: 支持SELECT查询语句
- ✏️ 数据更新操作: 支持INSERT、UPDATE、DELETE语句
- 📋 表管理: 列出所有表、查看表结构、创建新表
- 🗣️ 自然语言交互: 支持中文自然语言建表和查询
- 🔒 并发控制: 支持多Agent并发访问和事务管理
- 🐳 Docker部署: 完整的容器化支持
- ⚙️ 配置管理: 灵活的环境变量配置
- 📝 日志记录: 完整的操作日志记录
- 🧪 测试覆盖: 完整的测试和演示脚本
- 🌐 stdio模式: 标准MCP协议，支持自然语言交互
- 📋 初始化脚本: 支持配置文件方式启动和初始化
- 🚀 一键启动: Docker拉起即可使用，无需额外脚本
项目结构
db/
├── config/ # 配置模块
│ ├── __init__.py
│ ├── settings.py # 应用配置
│ └── example.env # 示例环境配置
├── database/ # 数据库模块
│ ├── __init__.py
│ ├── connection.py # 数据库连接管理
│ ├── advanced_connection.py # 高级连接管理
│ └── multi_agent_manager.py # 多Agent管理器
├── mcp/ # MCP服务器模块
│ ├── __init__.py
│ ├── server.py # 标准MCP服务器实现
│ ├── simple_server.py # 简化MCP服务器实现
│ ├── enhanced_server.py # 增强版MCP服务器（支持并发）
│ └── natural_language_server.py # 自然语言MCP服务器
├── init/ # 初始化脚本
│ └── init.sql # 数据库初始化SQL脚本
├── examples/ # 使用示例
│ ├── usage_examples.md # 详细使用示例
│ ├── concurrent_usage_example.py # 并发使用示例
│ ├── multi_agent_concurrency_example.py # 多Agent并发示例
│ └── natural_language_example.py # 自然语言使用示例
├── docs/ # 文档
│ ├── usage_guide.md # 使用指南
│ ├── concurrency_control.md # 并发控制文档
│ ├── multi_agent_concurrency.md # 多Agent并发文档
│ └── natural_language_usage.md # 自然语言使用指南
├── data/ # 数据目录（Docker卷挂载）
├── main.py # 主程序入口 (stdio模式)
├── main_enhanced.py # 增强版主程序（支持并发）
├── main_natural_language.py # 自然语言主程序
├── test_server.py # 测试脚本
├── test_stdio.py # stdio模式测试脚本
├── demo.py # 演示脚本
├── query.sh # 简化查询脚本
├── requirements.txt # Python依赖
├── Dockerfile # Docker镜像配置
├── docker-compose.yml # Docker Compose配置
├── .gitignore # Git忽略文件
├── .dockerignore # Docker忽略文件
└── README.md # 项目说明
快速开始
方法1: Docker启动（推荐）
- 克隆项目
git clone <repository-url>
cd db
- 启动服务器
# 标准模式
docker-compose up --build
# 增强模式（支持并发）
docker-compose -f docker-compose.yml up --build enhanced
# 自然语言模式
docker-compose -f docker-compose.yml up --build natural-language
- 服务器将自动初始化数据库并进入stdio模式
方法2: 本地启动
# 标准模式
python main.py
# 增强模式（支持并发）
python main_enhanced.py
# 自然语言模式
python main_natural_language.py
方法3: 直接Docker调用
# 构建镜像
docker-compose build
# 查询数据库信息
./query.sh info
# 查询所有用户
./query.sh users
# 执行自定义查询
./query.sh query "SELECT * FROM products"
方法4: 本地开发
- 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
- 安装依赖
pip install -r requirements.txt
- 运行测试
服务器模式
1. 标准模式 (main.py)
2. 增强模式 (main_enhanced.py)
- 支持多Agent并发
- 事务管理和乐观锁
- 一致性控制
- 适合多Agent协作
3. 自然语言模式 (main_natural_language.py)
- 支持中文自然语言建表
- 自然语言查询和更新
- 自动SQL生成
- 适合非技术用户
自然语言功能
自然语言建表
# 使用自然语言创建表
描述: "创建一个用户表，包含姓名、年龄、邮箱字段"
生成的SQL:
CREATE TABLE 用户 (姓名 TEXT, 年龄 INTEGER, 邮箱 TEXT)
自然语言查询
# 使用自然语言查询
描述: "查询所有年龄大于18的用户"
生成的SQL:
SELECT * FROM users WHERE age > 18
自然语言插入
# 使用自然语言插入数据
描述: "向用户表插入一个叫张三的用户，年龄25岁"
生成的SQL:
INSERT INTO users (name, age) VALUES ('张三', 25)
配置说明
环境变量
| 变量名 | 默认值 | 说明 |
|---|
DATABASE_PATH | data/sqlite.db | 数据库文件路径 |
INIT_SCRIPT | init/init.sql | 初始化SQL脚本路径 |
LOG_LEVEL | INFO | 日志级别 |
AGENT_ID | 自动生成 | Agent唯一标识符 |
USE_THREAD_SAFE | false | 是否使用线程安全模式 |
初始化脚本
服务器启动时会自动执行 init/init.sql 脚本，用于：
示例初始化脚本：
-- 创建用户表
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
email TEXT UNIQUE,
age INTEGER,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 插入示例数据
INSERT OR IGNORE INTO users (id, name, email, age) VALUES
(1, '张三', 'zhangsan@example.com', 25);
使用方法
简化查询脚本
使用 query.sh 脚本进行快速查询：
# 获取数据库信息
./query.sh info
# 列出所有表
./query.sh tables
# 查询所有用户
./query.sh users
# 执行自定义SQL查询
./query.sh query "SELECT * FROM products WHERE price > 100"
# 查看表结构
./query.sh describe users
直接Docker调用
# 基本格式
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "工具名", "arguments": {参数}}}' | docker run --rm -i -v $(pwd)/data:/app/data -v $(pwd)/config:/app/config -v $(pwd)/init:/app/init -e DATABASE_PATH=/app/data/sqlite.db -e INIT_SCRIPT=/app/init/init.sql db-sqlite-mcp-server
MCP工具说明
标准模式工具
1. sql_query
执行SQL查询语句，返回查询结果。
参数:
query (string, 必需): SQL查询语句params (array, 可选): 查询参数列表
示例:
{
"query": "SELECT * FROM users WHERE age > ?",
"params": ["18"]
}
2. sql_update
执行SQL更新语句（INSERT、UPDATE、DELETE）。
参数:
query (string, 必需): SQL更新语句params (array, 可选): 更新参数列表
示例:
{
"query": "INSERT INTO users (name, age) VALUES (?, ?)",
"params": ["张三", "25"]
}
3. list_tables
列出数据库中的所有表。
参数: 无
4. describe_table
描述指定表的结构。
参数:
table_name (string, 必需): 表名
5. create_table
创建新表。
参数:
table_name (string, 必需): 表名columns (string, 必需): 列定义SQL语句
6. database_info
获取数据库基本信息。
参数: 无
增强模式工具
除了标准工具外，还包含：
7. sql_transaction
执行事务操作。
参数:
operations (array, 必需): 操作列表isolation_level (string, 可选): 隔离级别
8. agent_status
获取当前Agent状态。
参数: 无
9. transaction_history
获取事务历史记录。
参数:
limit (integer, 可选): 返回记录数量限制
自然语言模式工具
10. natural_language_query
使用自然语言进行查询。
参数:
description (string, 必需): 自然语言查询描述
11. natural_language_create_table
使用自然语言创建表。
参数:
description (string, 必需): 自然语言表结构描述
12. natural_language_insert
使用自然语言插入数据。
参数:
description (string, 必需): 自然语言插入描述
13. natural_language_update
使用自然语言更新数据。
参数:
description (string, 必需): 自然语言更新描述
并发控制
多Agent并发
- 支持多个MCP Agent同时访问数据库
- 使用文件锁和事务管理确保数据一致性
- 支持乐观锁和悲观锁机制
事务隔离
- 支持不同的事务隔离级别
- 防止脏读、不可重复读和幻读
- 自动冲突检测和解决
开发指南
添加新工具
- 在对应的服务器类中添加工具定义
- 实现工具的处理方法
- 在
_call_tool 方法中添加路由
扩展自然语言功能
- 在
natural_language_server.py 中添加新的解析方法 - 更新字段类型映射
- 添加相应的测试用例
测试
运行测试
# 标准模式测试
python test_server.py
# 自然语言功能测试
python examples/natural_language_example.py
# 并发功能测试
python examples/multi_agent_concurrency_example.py
测试覆盖
- 基本SQL操作
- 自然语言解析
- 并发控制
- 错误处理
- 性能测试
部署
Docker部署
# 构建镜像
docker-compose build
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f
生产环境
- 使用持久化存储
- 配置日志轮转
- 设置监控告警
- 定期备份数据
贡献
欢迎提交Issue和Pull Request！
开发环境设置
- Fork项目
- 创建功能分支
- 提交更改
- 创建Pull Request
许可证
MIT License
更新日志
v2.0.0
- 添加自然语言建表功能
- 支持多Agent并发控制
- 增强事务管理
- 改进错误处理
v1.0.0
- 基础SQLite MCP服务器
- Docker容器化支持
- 基本CRUD操作