sqlite-mcp-server/README.md

SQLite MCP Server - A Model Context Protocol server for SQLite database operations

# SQLite MCP Server

一个基于 Model Context Protocol (MCP) 的 SQLite 数据库服务器，可以通过 npx 直接运行。

## 特性

- 🚀 通过 `npx` 一键启动，无需复杂安装
- 🗄️ 完整的 SQLite 数据库操作支持
- 🔧 基于 FastMCP 框架构建
- 📝 支持 SELECT、INSERT、UPDATE、DELETE 操作
- 🏗️ 支持表创建和结构查询
- 🔍 内置数据库表列表和描述功能

## 系统要求

- **Node.js**: >= 14.0.0 (当前检测到: v18.20.8)
- **Python**: >= 3.8 (当前检测到: Python 3.12.9)
- **pip**: 用于安装 Python 依赖

## 快速开始

### 使用 npx (推荐)

```bash
# 使用默认数据库 (test.db)
npx sqlite-mcp-server

# 指定自定义数据库路径
npx sqlite-mcp-server --db_path ./my_database.db
```

### 本地安装

```bash
npm install -g sqlite-mcp-server
sqlite-mcp-server --db_path ./my_database.db
```

## Python 依赖

本包会自动安装以下 Python 依赖：

- `fastmcp` (当前版本: 2.5.1)
- `mcp`

如果自动安装失败，可以手动安装：

```bash
pip install fastmcp mcp
```

## 使用方法

### 命令行选项

```bash
sqlite-mcp-server [选项]

选项:
  --db_path <路径>    SQLite 数据库文件路径 (默认: test.db)
  --help, -h          显示帮助信息
```

### 示例

```bash
# 启动服务器，使用默认数据库
npx sqlite-mcp-server

# 使用自定义数据库路径
npx sqlite-mcp-server --db_path ./data/my_app.db

# 使用内存数据库
npx sqlite-mcp-server --db_path ":memory:"
```

## MCP 工具

服务器提供以下 MCP 工具：

### `read_query`
执行 SELECT 查询语句
```python
# 示例
read_query("SELECT * FROM users WHERE age > 18")
```

### `write_query`
执行 INSERT、UPDATE 或 DELETE 语句
```python
# 示例
write_query("INSERT INTO users (name, age) VALUES ('张三', 25)")
write_query("UPDATE users SET age = 26 WHERE name = '张三'")
write_query("DELETE FROM users WHERE age < 18")
```

### `create_table`
创建新表
```python
# 示例
create_table("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
```

### `list_tables`
列出数据库中的所有表
```python
# 示例
list_tables()
```

### `describe_table`
获取指定表的结构信息
```python
# 示例
describe_table("users")
```

## 开发

### 项目结构

```
sqlite-mcp-server/
├── bin/
│   └── sqlite-mcp-server.js    # Node.js 包装器
├── scripts/
│   └── install-python-deps.js  # 依赖安装脚本
├── python/
│   ├── sqlite.py               # 主要的 Python MCP 服务器
│   ├── log.py                  # 日志工具
│   └── requirements.txt        # Python 依赖
├── package.json
└── README.md
```

### 本地开发

```bash
# 克隆项目
git clone https://github.com/yourusername/sqlite-mcp-server.git
cd sqlite-mcp-server

# 安装依赖
npm install

# 运行
npm start
```

## 故障排除

### Python 未找到
```
Error: Python not found. Please install Python 3.8 or higher.
```
**解决方案**: 安装 Python 3.8+ 并确保在 PATH 中可用。

### pip 安装失败
```
Failed to install some Python dependencies
```
**解决方案**: 手动安装依赖：
```bash
pip install -r python/requirements.txt
```

### 权限错误
在某些系统上可能需要使用 `sudo` 或管理员权限：
```bash
sudo npm install -g sqlite-mcp-server
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本
- 支持基本的 SQLite 操作
- 通过 npx 一键启动
- 自动依赖管理