Name: libSQL数据库协议服务
Author: Xexr

使用说明

xexr的MCP libSQL

用于libSQL数据库操作的模型上下文协议（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桌面 使用您的Node.js路径和数据库URL（请参阅下面的配置示例）

🚀 状态

✅ 完整的数据库管理功能 -实施并测试了所有6个核心工具
✅ 全面的安全验证 -67项安全测试，涵盖所有注射载体
✅ 广泛的测试覆盖范围 -总共244次测试（177个单元+67个安全），通过率100%
✅ 生产部署已验证 -成功与MCP客户合作
✅ 稳健的错误处理 -连接重试、优雅降级和审核日志记录

🛠️ 特性

可用工具

读取查询：执行带有全面安全验证的SELECT查询
写查询：具有事务支持的INSERT/UPDATE/DELETE操作
创建表格：用于创建具有安全措施的表的DDL操作
改变桌子：表结构修改（ADD/RENAME/DROP操作）
列表表格：使用筛选选项浏览数据库元数据
描述表格：具有多种输出格式的表模式检查

安全性和可靠性

多层SQL注入防护 具有全面的安全验证
连接池 具有健康监测和自动重试逻辑
交易支持 具有错误自动回滚功能
全面的审计日志记录 安全合规性

🔐 安全详细信息： 看 docs/SECURITY.md 用于全面的安全功能和测试。

开发者体验

漂亮的表格格式 正确对齐和NULL处理
性能指标 显示所有操作
清除错误消息 具有可操作的上下文
参数化查询支持 用于安全数据处理
开发模式 具有增强的日志记录和热重载功能

📋 先决条件

Node.js 20+
pnpm （或npm）包管理器
libSQL数据库 （基于文件或远程）
克劳德桌面版 （用于MCP集成）

平台要求

macOS：原生Node.js安装
Linux：原生Node.js安装
视窗：原生Node.js安装或WSL2与Node.js安装

🔧 安装

# Use your package manager of choice, e.g. npm, pnpm, bun etc

# Install globally
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # check version

# ...or build from the repository
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # Install dependencies
pnpm build # Build the project
node dist/index.js -v  # check version

🚀 用法

局部测试

下面假设全局安装，如果使用本地构建，请将“mcp-libsql”替换为“node-dist/index.js”

# Test with file database (default: file-only logging)
mcp-libsql --url file:///tmp/test.db

# Test with HTTP database
mcp-libsql --url http://127.0.0.1:8080

# Test with Turso database (environment variable, alternatively export the env var)
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# Test with Turso database (CLI parameter)
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# Development mode with console logging
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# Test with different logging modes
mcp-libsql --url --log-mode both file:///tmp/test.db

Claude桌面集成

根据您的操作系统在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 for node进行全局安装的替代配置

{
  "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设置

创建和配置数据库：

# Create database
turso db create my-app-db

# Get database URL
turso db show my-app-db --url
# Output: libsql://my-app-db-username.turso.io

# Create auth token
turso auth token create --name "mcp-libsql-token"
# Output: your-long-auth-token-string

配置Claude桌面：

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://my-app-db-username.turso.io"
      ]
    }
  }
}

测试连接：

# Test locally first
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运行SQL查询：
```
Can you run this SQL query: SELECT 1 as test
```

📋 可用工具

读取查询 -执行带有安全验证的SELECT查询
写查询 -插入/更新/删除，支持事务处理
创建表格 -使用DDL安全性创建表
改变桌子 -修改表结构（添加/重命名/删除）
列表表格 -浏览数据库元数据和对象
描述表格 -检查表架构和结构

📖 API详细文件： 看 docs/API.md文件获取完整的输入/输出示例和参数。

🧪 测试

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test security-verification

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

测试覆盖率：403个测试，涵盖所有功能，包括边缘情况、错误场景、CLI参数、身份验证和全面的安全验证。

⚠️ 常见问题

1.构建失败

# Clean and rebuild
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解析错误（已解决）

Expected ',' or ']' after array element in JSON

已解决：此问题是由stdout控制台日志记录引起的。这 --log-mode 选项现在默认为 file 防止此问题的模式。如果您看到这些错误，请确保您使用的是默认值 --log-mode file 或未指定 --log-mode 完全。请注意，该错误是无害的，如果您希望进行控制台日志记录，该工具仍将使用它。

6.数据库连接问题

# Test database connectivity
sqlite3 /tmp/test.db "SELECT 1"

# Fix permissions
chmod 644 /path/to/database.db

🔧 完整的故障排除指南： 看 docs/TROUBLESHOOTING.md 获取所有问题的详细解决方案。

🏗️ 建筑

使用TypeScript和现代Node.js模式构建：

连接池 具有健康监控和重试逻辑
基于工具的架构 具有一致的验证和错误处理
安全第一设计 具有多层输入验证功能
综合测试 244个测试涵盖所有场景

🤝 贡献

遵循TypeScript严格模式和现有代码模式
为新功能编写测试
维护安全措施
更新文档

发展： pnpm dev • 构建： pnpm build • 测试： pnpm test

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

使用说明

xexr的MCP libSQL

🔧 快速开始

🚀 状态

🛠️ 特性

可用工具

安全性和可靠性

开发者体验

📋 先决条件

平台要求

🔧 安装

🚀 用法

局部测试

Claude桌面集成

macOS配置

Linux配置

Windows（WSL2）配置

数据库身份验证

方法1：环境变量（推荐）

方法2:CLI参数

获取您的Turso认证令牌

安全最佳实践

示例：完成Turso设置

配置说明

📋 可用工具

🧪 测试

⚠️ 常见问题

1.构建失败

2.Node.js版本问题（macOS）

3.服务器无法启动

4.工具不可用

5.JSON解析错误（已解决）

6.数据库连接问题

🏗️ 建筑

🤝 贡献

📄 许可证

🔗 链接

相关 MCP

MySQL数据库管理工具

MongoDB 数据库 MCP 服务器

PostgreSQL管理服务器

PocketBase 数据库 MCP 服务器

SQLite数据库服务

MySQL数据库操作工具