麦克佩-库恩SQL
项目介绍
技术文档摘要
MCP libSQL by xexr
这是一个用于 libSQL 数据库操作的 Model Context Protocol (MCP) 服务器，通过 Claude Desktop、Claude Code、Cursor 和其他兼容 MCP 的客户端提供安全的数据库访问。
运行在 Node 上，使用 TypeScript 编写。
🔧 快速开始
-
安装：
pnpm install -g @xexr/mcp-libsql -
本地测试：
mcp-libsql --url file:///tmp/test.db --log-mode console -
配置 Claude Desktop 使用你的 Node.js 路径和数据库 URL（参见下面的配置示例）
🚀 状态
✅ 完整的数据库管理功能 - 所有 6 个核心工具已实现并经过测试
✅ 全面的安全验证 - 67 项安全测试覆盖所有注入向量
✅ 广泛的测试覆盖率 - 总计 244 项测试（177 项单元测试 + 67 项安全测试），通过率 100%
✅ 生产部署验证 - 成功与 MCP 客户端配合工作
✅ 强大的错误处理 - 连接重试、优雅降级和审计日志
🛠️ 功能
可用工具
- read-query：执行带有全面安全验证的 SELECT 查询
- write-query：支持事务的 INSERT/UPDATE/DELETE 操作
- create-table：带有安全措施的表创建 DDL 操作
- alter-table：表结构修改（添加/重命名/删除操作）
- list-tables：带有过滤选项的数据库元数据浏览
- describe-table：多种输出格式的表模式检查
安全与可靠性
- 多层 SQL 注入防护，带有全面的安全验证
- 连接池，带有健康监控和自动重试逻辑
- 事务支持，错误时自动回滚
- 全面的审计日志，符合安全合规性要求
🔐 安全详情：请参阅 docs/SECURITY.md，了解全面的安全特性和测试。
开发者体验
- 美观的表格格式化，带有正确的对齐和 NULL 处理
- 性能指标，显示所有操作
- 清晰的错误消息，带有可操作的上下文
- 参数化查询支持，确保安全的数据处理
- 开发模式，带有增强的日志记录和热重载
📋 先决条件
- Node.js 20+
- pnpm（或 npm）包管理器
- libSQL 数据库（基于文件或远程）
- Claude Desktop（用于 MCP 集成）
平台需求
- macOS：原生 Node.js 安装
- Linux：原生 Node.js 安装
- Windows：原生 Node.js 安装或带有 Node.js 安装的 WSL2
🔧 安装
# 使用你喜欢的包管理器，例如 npm、pnpm、bun 等
# 全局安装
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # 检查版本
# 或从仓库构建
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # 安装依赖
pnpm build # 构建项目
node dist/index.js -v # 检查版本
🚀 使用
本地测试
假设全局安装，如果使用本地构建，请将 "mcp-libsql" 替换为 "node dist/index.js"
# 使用文件数据库测试（默认：仅文件日志）
mcp-libsql --url file:///tmp/test.db
# 使用 HTTP 数据库测试
mcp-libsql --url http://127.0.0.1:8080
# 使用 Turso 数据库测试（环境变量，或者导出环境变量）
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"
# 使用 Turso 数据库测试（CLI 参数）
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"
# 带有控制台日志的开发模式
mcp-libsql --dev --log-mode console --url file:///tmp/test.db
# 使用不同的日志模式测试
mcp-libsql --url --log-mode both file:///tmp/test.db
Claude Desktop 集成
根据操作系统配置 Claude Desktop 中的 MCP 服务器：
macOS 配置
- 在
~/Library/Application Support/Claude/claude_desktop_config.json创建配置文件：
全局安装
{
"mcpServers": {
"mcp-libsql": {
"command": "mcp-libsql",
"args": [
"--url",
"file:///Users/username/database.db"
]
}
}
}
替代配置，适用于本地构建安装：
{
"mcpServers": {
"mcp-libsql": {
"command": "node",
"args": [
"/Users/username/projects/mcp-libsql/dist/index.js",
"--url",
"file:///Users/username/database.db"
],
}
}
}
替代配置，使用 nvm lts 的全局安装：
{
"mcpServers": {
"mcp-libsql": {
"command": "zsh",
"args": [
"-c",
"source ~/.nvm/nvm.sh && nvm use --lts > /dev/null && mcp-libsql --url file:///Users/[username]/database.db",
],
}
}
}
重要提示：推荐使用全局安装方法，因为它会自动处理 PATH。
Linux 配置
- 在
~/.config/Claude/claude_desktop_config.json创建配置文件：
全局安装
{
"mcpServers": {
"mcp-libsql": {
"command": "mcp-libsql",
"args": [
"--url",
"file:///home/username/database.db"
]
}
}
}
替代配置，适用于本地构建安装：
{
"mcpServers": {
"mcp-libsql": {
"command": "node",
"args": [
"/home/username/projects/mcp-libsql/dist/index.js",
"--url",
"file:///home/username/database.db"
],
}
}
}
Windows (WSL2) 配置
- 在
%APPDATA%\Claude\claude_desktop_config.json创建配置文件：
全局安装
{
"mcpServers": {
"mcp-libsql": {
"command": "wsl.exe",
"args": [
"-e",
"bash",
"-c",
"mcp-libsql --url file:///home/username/database.db",
]
}
}
}
替代配置，适用于本地构建安装：
{
"mcpServers": {
"mcp-libsql": {
"command": "wsl.exe",
"args": [
"-e",
"bash",
"-c",
"/home/username/projects/mcp-libsql/dist/index.js --url file:///home/username/database.db",
]
}
}
}
替代配置，使用 nvm 的全局安装：
{
"mcpServers": {
"mcp-libsql": {
"command": "wsl.exe",
"args": [
"-e",
"bash",
"-c",
"source ~/.nvm/nvm.sh && mcp-libsql --url file:///home/username/database.db",
]
}
}
}
重要提示：使用 wsl.exe -e（而不是仅仅 wsl.exe），以确保命令正确处理，并避免 Windows 上服务器命令接收的问题。
数据库认证
对于 Turso（以及其他需要凭据的）数据库，你需要一个认证令牌。有两种安全的方法来提供它：
全局安装如下所示，根据你的设置进行调整
方法 1：环境变量（推荐）
配置 Claude Desktop 使用环境变量（macOS/Linux 示例）：
export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"
{
"mcpServers": {
"mcp-libsql": {
"command": "mcp-libsql",
"args": [
"--url",
"libsql://your-database.turso.io"
]
}
}
}
方法 2：CLI 参数
{
"mcpServers": {
"mcp-libsql": {
"command": "mcp-libsql",
"args": [
"--url",
"libsql://your-database.turso.io",
"--auth-token",
"your-turso-auth-token-here"
]
}
}
}
获取你的 Turso 认证令牌
-
安装 Turso CLI：
curl -sSfL https://get.tur.so/install.sh | bash -
登录到 Turso：
turso auth login -
创建一个认证令牌：
turso auth token create --name "mcp-libsql" -
获取你的数据库 URL：
turso db show your-database-name --url
安全最佳实践
- 环境变量比 CLI 参数更安全（令牌不会出现在进程列表中）
- MCP 配置文件可能包含令牌 - 确保它们不提交到版本控制系统
- 考虑使用外部密钥管理系统 用于生产环境
- 使用范围令牌，具有最小权限
- 定期轮换令牌 以增强安全性
- 通过 Turso 仪表板监控令牌使用情况
示例：完整的 Turso 设置
-
创建并配置数据库：
# 创建数据库 turso db create my-app-db # 获取数据库 URL turso db show my-app-db --url # 输出：libsql://my-app-db-username.turso.io # 创建认证令牌 turso auth token create --name "mcp-libsql-token" # 输出：your-long-auth-token-string -
配置 Claude Desktop：
export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"{ "mcpServers": { "mcp-libsql": { "command": "mcp-libsql", "args": [ "--url", "libsql://my-app-db-username.turso.io" ] } } } -
测试连接：
# 先本地测试 mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console
配置说明
- 文件路径：使用绝对路径以避免路径解析问题
- 数据库 URL：
- 文件数据库：
file:///absolute/path/to/database.db - HTTP 数据库：
http://hostname:port - libSQL/Turso：
libsql://your-database.turso.io
- 文件数据库：
- Node.js 路径：使用
which node查找你的 Node.js 安装路径 - 工作目录：设置
cwd以确保相对路径正确工作 - 认证：对于 Turso 数据库，使用环境变量进行安全令牌处理
- 日志模式：
- 默认
file模式防止 MCP 协议中的 JSON 解析错误 - 使用
--log-mode console进行开发调试 - 使用
--log-mode both进行全面日志记录 - 使用
--log-mode none禁用所有日志
- 默认
-
完全重启 Claude Desktop 后更新配置
-
通过请求 Claude 运行 SQL 查询来测试集成：
你能运行这个 SQL 查询吗：SELECT 1 as test
📋 可用工具
- read-query - 执行带有安全验证的 SELECT 查询
- write-query - 支持事务的 INSERT/UPDATE/DELETE
- create-table - 带有 DDL 安全性的 CREATE TABLE
- alter-table - 修改表结构（添加/重命名/删除）
- list-tables - 浏览数据库元数据和对象
- describe-table - 检查表模式和结构
📖 详细 API 文档：请参阅 docs/API.md，了解完整的输入/输出示例和参数。
🧪 测试
# 运行所有测试
pnpm test
# 在监视模式下运行测试
pnpm test:watch
# 运行带覆盖率的测试
pnpm test:coverage
# 运行特定测试文件
pnpm test security-verification
# 代码检查
pnpm lint
# 修复代码检查问题
pnpm lint:fix
# 类型检查
pnpm typecheck
测试覆盖率：403 项测试涵盖所有功能，包括边缘案例、错误场景、CLI 参数、认证和全面的安全验证。
⚠️ 常见问题
1. 构建失败
# 清除并重新构建
rm -rf dist node_modules
pnpm install && pnpm build
2. Node.js 版本问题（macOS）
SyntaxError: Unexpected token '??='
问题：Claude Desktop 可能默认使用系统上的旧版 Node.js，该版本不支持所需的功能集。
解决方案：使用上面展示的全局安装和 nvm 节点选择方法。
3. 服务器无法启动
- 对于全局安装：
pnpm install -g @xexr/mcp-libsql - 对于本地安装：确保运行了
pnpm build并且存在dist/index.js - 本地测试：
mcp-libsql --url file:///tmp/test.db - 更新配置后重启 Claude Desktop
4. 工具不可用
- 验证数据库 URL 是否可访问
- 检查 Claude Desktop 日志中的连接错误
- 使用简单的文件数据库测试：
file:///tmp/test.db
5. JSON 解析错误（已解决）
预期 ',' 或 ']' 在 JSON 数组元素之后
已解决：此问题由 stdout 控制台日志引起。--log-mode 选项现在默认为 file 模式，这可以防止此问题。如果你看到这些错误，请确保你正在使用默认的 --log-mode file 或根本不指定 --log-mode。请注意，此错误无害，即使你希望有控制台日志，工具仍然可以正常工作。
6. 数据库连接问题
# 测试数据库连接性
sqlite3 /tmp/test.db "SELECT 1"
# 修复权限
chmod 644 /path/to/database.db
🔧 完整的故障排除指南：请参阅 docs/TROUBLESHOOTING.md，了解所有问题的详细解决方案。
🏗️ 架构
使用 TypeScript 和现代 Node.js 模式构建：
- 连接池，带有健康监控和重试逻辑
- 工具架构，带有一致的验证和错误处理
- 安全优先设计，带有多层次输入验证
- 全面测试，244 项测试涵盖所有场景
🤝 贡献
- 遵循 TypeScript 严格模式和现有代码模式
- 为新特性编写测试
- 维护安全措施
- 更新文档
开发：pnpm dev • 构建：pnpm build • 测试：pnpm test
📄 许可证
MIT 许可证 - 详情请参阅 LICENSE 文件。