Skip to main content
Glama
Rikxed

SQLite MCP Server

by Rikxed

SQLite MCP 服务器

一个基于Python实现的SQLite标准MCP(Model Context Protocol)服务器,支持数据库的读写操作,使用Docker进行容器化部署,以stdio模式运行,支持自然语言交互。

功能特性

  • 🔍 SQL查询执行: 支持SELECT查询语句

  • ✏️ 数据更新操作: 支持INSERT、UPDATE、DELETE语句

  • 📋 表管理: 列出所有表、查看表结构、创建新表

  • 🗣️ 自然语言交互: 支持中文自然语言建表和查询

  • 🔒 并发控制: 支持多Agent并发访问和事务管理

  • 🐳 Docker部署: 完整的容器化支持

  • ⚙️ 配置管理: 灵活的环境变量配置

  • 📝 日志记录: 完整的操作日志记录

  • 🧪 测试覆盖: 完整的测试和演示脚本

  • 🌐 stdio模式: 标准MCP协议,支持自然语言交互

  • 📋 初始化脚本: 支持配置文件方式启动和初始化

  • 🚀 一键启动: Docker拉起即可使用,无需额外脚本

Related MCP server: mcp-sqlite-chat

项目结构

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启动(推荐)

  1. 克隆项目

    git clone <repository-url>
    cd db
  2. 启动服务器

    # 标准模式
    docker-compose up --build
    
    # 增强模式(支持并发)
    docker-compose -f docker-compose.yml up --build enhanced
    
    # 自然语言模式
    docker-compose -f docker-compose.yml up --build natural-language
  3. 服务器将自动初始化数据库并进入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: 本地开发

  1. 创建虚拟环境

    python3 -m venv venv
    source venv/bin/activate
  2. 安装依赖

    pip install -r requirements.txt
  3. 运行测试

    python test_server.py

服务器模式

1. 标准模式 (main.py)

  • 基本的SQL操作

  • 单线程安全

  • 适合单Agent使用

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同时访问数据库

  • 使用文件锁和事务管理确保数据一致性

  • 支持乐观锁和悲观锁机制

事务隔离

  • 支持不同的事务隔离级别

  • 防止脏读、不可重复读和幻读

  • 自动冲突检测和解决

开发指南

添加新工具

  1. 在对应的服务器类中添加工具定义

  2. 实现工具的处理方法

  3. 在 _call_tool 方法中添加路由

扩展自然语言功能

  1. 在 natural_language_server.py 中添加新的解析方法

  2. 更新字段类型映射

  3. 添加相应的测试用例

测试

运行测试

# 标准模式测试
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!

开发环境设置

  1. Fork项目

  2. 创建功能分支

  3. 提交更改

  4. 创建Pull Request

许可证

MIT License

更新日志

v2.0.0

  • 添加自然语言建表功能

  • 支持多Agent并发控制

  • 增强事务管理

  • 改进错误处理

v1.0.0

  • 基础SQLite MCP服务器

  • Docker容器化支持

  • 基本CRUD操作

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides SQLite database operations. Allows AI assistants to query, modify and manage SQLite databases through the Model Context Protocol.
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying and managing a SQLite database using natural language, with an MCP server and Groq LLM.
    -
  • A
    license
    C
    quality
    A
    maintenance
    An MCP server for interacting with SQLite databases, enabling SQL query execution, schema inspection, and CRUD operations.
    7
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for working with encrypted SQLite databases (SQLCipher), enabling database exploration, SQL queries, and CRUD operations through natural language.
    Apache 2.0