使用说明

SQLite MCP服务器

一种模型上下文协议（MCP）服务器，通过标准化接口提供SQLite数据库操作。该服务器允许AI助手和其他MCP客户端使用一组预定义的工具与SQLite数据库进行交互。包括一个可选的HTTP包装器，便于测试和开发。

特性

核心MCP服务器

标准MCP协议：AI助手和MCP客户端的干净实施
数据库操作：列出表、描述架构、运行查询、插入/更新/删除数据
安全：仅使用参数化语句的SELECT查询，以防止SQL注入
综合录井：调试传入请求和传出响应

开发与测试

HTTP包装器：可选HTTP API，便于使用Postman/ccurl进行测试
邮差收藏：随时可用的API测试集合和示例
快速启动脚本：自动设置数据库创建和服务器启动
端口冲突解决：自动检测和解决端口冲突

部署和集成

Docker就绪：容器化，便于部署和MCP目录兼容性
Docker脚本：全面的Docker管理，包括构建、运行、停止和监控
环境配置：灵活的数据库路径和端口配置
生产就绪：非root用户、健康检查和正确的错误处理

先决条件

Node.js 18或更高版本
SQLite 3（包含在Docker镜像中）

快速开始

使用我们的快速入门脚本，在几秒钟内即可启动并运行：

方案1：地方发展

# Clone the repository
git clone <repository-url>
cd sqlite-mcp-server

# Run the quickstart script
./quickstart.sh

此脚本将：

✅ 检查Node.js版本（需要18+）
✅ 自动安装依赖项
✅ 使用测试数据创建示例数据库
✅ 启动MCP服务器和HTTP包装服务器

服务器将使用包含以下内容的示例数据库运行：

3名用户（John Doe、Jane Smith、Bob Johnson）
3个类别（科技、旅游、食品）
4个有关系的示例帖子

可用服务器：

MCP服务器：已准备好进行stdio通信
HTTP服务器：可在http://localhost:3001用于邮差/卷发测试

选项2：使用预构建的Docker镜像

如果你想在不构建的情况下立即尝试：

# Create data directory
mkdir -p data

可用的Docker镜像：

Docker Hub （推荐）： arungupta/sqlite-mcp-server:latest
GitHub容器注册表: ghcr.io/arun-gupta/sqlite-mcp-server:latest

HTTP模式（推荐）-HTTP API和MCP服务器

# Run in HTTP mode (includes both HTTP API and MCP server)
# Option 1: Docker Hub (recommended)
docker run -d \
  --name sqlite-mcp-http \
  -p 3001:3001 \
  -v $(pwd)/data:/data \
  -e SQLITE_DB_PATH=/data/database.db \
  -e SERVER_MODE=http \
  -e HTTP_PORT=3001 \
  arungupta/sqlite-mcp-server:latest

# Option 2: GitHub Container Registry
docker run -d \
  --name sqlite-mcp-http \
  -p 3001:3001 \
  -v $(pwd)/data:/data \
  -e SQLITE_DB_PATH=/data/database.db \
  -e SERVER_MODE=http \
  -e HTTP_PORT=3001 \
  ghcr.io/arun-gupta/sqlite-mcp-server:latest

# Test HTTP endpoints (curl)
curl http://localhost:3001/health
curl http://localhost:3001/tables
curl http://localhost:3001/tables/users
curl -X POST http://localhost:3001/query \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT * FROM users"}'

# Test MCP server directly (stdio) - same container!
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tables","arguments":{}}}' | docker exec -i sqlite-mcp-http node dist/server.js
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"describe_table","arguments":{"table_name":"users"}}}' | docker exec -i sqlite-mcp-http node dist/server.js
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_query","arguments":{"query":"SELECT * FROM users"}}}' | docker exec -i sqlite-mcp-http node dist/server.js

仅限MCP模式-用于直接MCP客户端集成

# Run in MCP mode only (for AI assistants and MCP clients)
# Option 1: Docker Hub (recommended)
docker run -d \
  --name sqlite-mcp \
  -v $(pwd)/data:/data \
  -e SQLITE_DB_PATH=/data/database.db \
  arungupta/sqlite-mcp-server:latest

# Option 2: GitHub Container Registry
docker run -d \
  --name sqlite-mcp \
  -v $(pwd)/data:/data \
  -e SQLITE_DB_PATH=/data/database.db \
  ghcr.io/arun-gupta/sqlite-mcp-server:latest

# Test MCP server (stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tables","arguments":{}}}' | docker exec -i sqlite-mcp node dist/server.js

测试HTTP包装器（邮递员）

从以下位置导入提供的Postman收藏 examples/postman-collection.json 对于一组完整的预配置请求。

安装

地方发展

克隆存储库：

git clone <repository-url>
cd sqlite-mcp-server

安装依赖项：

npm install

启动服务器：

# MCP server only
npm start

# HTTP wrapper for testing
npm run http

# Both servers (recommended)
./quickstart.sh

CI/CD管道

该项目使用GitHub Actions进行自动化构建、测试和发布：

🚀 自动化工作流程

每一次推 main 分支触发器：

✅ 构建与测试:
- TypeScript编译和类型检查
- Docker镜像构建
- HTTP模式测试（健康端点）
- MCP模式测试（stdio通信）
✅ 发布Docker镜像:
- Docker Hub: arungupta/sqlite-mcp-server:latest
- GitHub容器注册表: ghcr.io/arun-gupta/sqlite-mcp-server:latest
✅ 发布npm包:
- GitHub npm注册表: @arun-gupta/sqlite-mcp-server@{timestamp}.0.0

📋 工作流状态

工作流状态显示在本README顶部的徽章中。

🔧 手动触发

您可以手动触发工作流：

首选行动
选择“Docker镜像CI”
点击“运行工作流”

码头工人

Docker镜像支持两种模式：

MCP模式 （默认）：用于客户端集成的持久化MCP服务器
HTTP模式：用于测试和开发的HTTP API服务器

使用 SERVER_MODE 用于在模式之间切换的环境变量。

快速开始

使用Docker脚本（推荐）：

# Build and test MCP server
./docker-run.sh build
./docker-run.sh run

# Or run with HTTP wrapper for testing
./docker-run.sh run-http

使用npm脚本：

# Build and test MCP server
npm run docker:build
npm run docker:run

# Or run with HTTP wrapper for testing
npm run docker:run-http

Docker模式

Docker镜像支持两种模式：

HTTP模式 （推荐）：包括HTTP API和MCP服务器
MCP模式：仅直接MCP服务器（无HTTP开销）

快速模式切换：

# Check which mode is running
docker ps

# Stop current container
docker stop sqlite-mcp sqlite-mcp-http 2>/dev/null || true

# Switch to HTTP mode
docker run -d --name sqlite-mcp-http -p 3001:3001 -v $(pwd)/data:/data -e SERVER_MODE=http -e HTTP_PORT=3001 sqlite-mcp-server

# Switch to MCP mode
docker run -d --name sqlite-mcp -v $(pwd)/data:/data -e SERVER_MODE=mcp sqlite-mcp-server

发布到Docker Hub

要创建和发布 arungupta/sqlite-mcp-server 图片：

注：替换 arungupta 如果您想发布到自己的存储库，请使用您的Docker Hub用户名。

# Build with the correct tag
docker build -t arungupta/sqlite-mcp-server:latest .

# Test the image locally (persistent mode)
docker run -d \
  --name sqlite-mcp-server \
  -v $(pwd)/data:/data \
  -e SQLITE_DB_PATH=/data/database.db \
  arungupta/sqlite-mcp-server:latest

# Check logs to verify it's running
docker logs sqlite-mcp-server

# Clean up container
docker stop sqlite-mcp-server && docker rm sqlite-mcp-server

# Login to Docker Hub (if not already logged in)
docker login

# Push to Docker Hub
docker push arungupta/sqlite-mcp-server:latest

# Tag with version (optional)
docker tag arungupta/sqlite-mcp-server:latest arungupta/sqlite-mcp-server:1.0.0
docker push arungupta/sqlite-mcp-server:1.0.0

完整测试套件

运行完整的测试套件以验证所有功能：

npm test

这将启动服务器并发送一系列测试消息，以验证所有工具是否正常工作。

安全考虑

查询验证：中只允许SELECT查询 run_query 防止破坏性操作的工具
参数化查询：所有数据库操作都使用预处理语句来防止SQL注入
非root用户：为了安全起见，Docker容器以非root用户身份运行
输入验证：所有工具参数都根据其模式进行验证

日志记录

服务器为调试提供全面的日志记录：

所有传入的MCP请求都记录到stderr
所有传出的响应都会记录到stderr
记录数据库连接状态
记录工具执行错误及其详细信息

Docker MCP目录

此服务器旨在与Docker MCP目录兼容。这 mcp.json 清单文件定义了MCP客户端的服务器配置。

Docker目录元数据

名字：arungupta/sqlitemcp服务器
版本: 1.0.0
描述：通过MCP进行SQLite数据库操作
作者：阿伦·古普塔
许可证：Apache 2.0
Docker Hub: arungupta/sqlite-mcp-server

发展

项目结构

sqlite-mcp-server/
├── src/
│   ├── server.js          # Main MCP server implementation
│   └── http-wrapper.js    # HTTP wrapper for testing
├── test/
│   └── test.js           # Test suite
├── examples/
│   ├── setup-database.ts  # Database setup script
│   └── postman-collection.json # Postman collection
├── package.json          # Node.js dependencies
├── mcp.json             # MCP manifest
├── Dockerfile           # Docker configuration
├── docker-run.sh        # Docker management script
├── quickstart.sh        # Quick setup script
└── README.md           # This file

故障排除

常见问题

数据库连接失败
- 检查一下 SQLITE_DB_PATH 设置正确
- 确保数据库文件可访问
- 验证SQLite是否已安装（在Docker镜像中）
权限不足
- 确保数据库文件具有适当的读/写权限
- 在Docker中，检查卷装载权限
未找到工具
- 验证工具名称是否正确
- 检查该工具是否在服务器中正确注册

调试模式

通过设置环境变量启用详细日志记录：

export DEBUG=1

许可证

此项目根据Apache许可证2.0获得许可-请参阅许可证文件以获取详细信息。

SQLite数据库操作服务

使用说明

SQLite MCP服务器

特性

核心MCP服务器

开发与测试

部署和集成

先决条件

快速开始

方案1：地方发展

选项2：使用预构建的Docker镜像

HTTP模式（推荐）-HTTP API和MCP服务器

仅限MCP模式-用于直接MCP客户端集成

测试HTTP包装器（邮递员）

安装

地方发展

CI/CD管道

🚀 自动化工作流程

📋 工作流状态

🔧 手动触发

码头工人

快速开始

Docker模式

发布到Docker Hub

完整测试套件

安全考虑

日志记录

Docker MCP目录

Docker目录元数据

发展

项目结构

故障排除

常见问题

调试模式

许可证

测试提交以触发工作流

使用说明

SQLite MCP服务器

特性

核心MCP服务器

开发与测试

部署和集成

先决条件

快速开始

方案1：地方发展

选项2：使用预构建的Docker镜像

HTTP模式（推荐）-HTTP API和MCP服务器

仅限MCP模式-用于直接MCP客户端集成

测试HTTP包装器（邮递员）

安装

地方发展

CI/CD管道

🚀 自动化工作流程

📋 工作流状态

🔧 手动触发

码头工人

快速开始

Docker模式

发布到Docker Hub

完整测试套件

安全考虑

日志记录

Docker MCP目录

Docker目录元数据

发展

项目结构

故障排除

常见问题

调试模式

许可证

测试提交以触发工作流

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器