MCP libSQL by xexr

MCP libSQL by xexr

用于 libSQL 数据库操作的 Model Context Protocol（MCP）服务，可通过 Claude Desktop、Claude Code、Cursor 和其他兼容 MCP 的客户端安全访问数据库。

基于 Node 运行，使用 TypeScript 编写

🔧 快速开始

1. 安装：

   pnpm install -g @xexr/mcp-libsql
   

2. 本地测试：

   mcp-libsql --url file:///tmp/test.db --log-mode console
   

3. 使用你的 Node.js 路径和数据库 URL 配置 Claude Desktop（请参阅下方的配置示例）

🚀 状态

✅ 完整的数据库管理能力 - 已实现并测试全部 6 项核心工具
✅ 全面的安全验证 - 67 项安全测试，覆盖所有注入攻击向量
✅ 广泛的测试覆盖 - 共 244 项测试（177 项单元测试 + 67 项安全测试），通过率 100%
✅ 已验证生产部署 - 已成功与 MCP 客户端配合使用
✅ 稳健的错误处理 - 连接重试、优雅降级和审计日志记录

🛠️ 功能

可用工具

• read-query：执行 SELECT 查询，并进行全面的安全验证
• write-query：执行 INSERT/UPDATE/DELETE 操作，并支持事务
• create-table：执行建表 DDL 操作，并采取安全措施
• alter-table：修改表结构（ADD/RENAME/DROP 操作）
• 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

🔧 安装

# 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 Desktop 集成

根据你的操作系统，在 Claude Desktop 中配置 MCP 服务：

macOS 配置

1. 创建配置文件，路径为 ~/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 安装 node 进行全局安装的替代配置

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

1. 创建配置文件，路径为 ~/.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）配置

1. 创建配置文件，路径为 %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 安装 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 身份验证令牌

1. 安装 Turso CLI：

   curl -sSfL https://get.tur.so/install.sh | bash
   

2. 登录 Turso：

   turso auth login
   

3. 创建身份验证令牌：

   turso auth token create --name "mcp-libsql"
   

4. 获取数据库 URL：

   turso db show your-database-name --url
   

安全最佳实践

• 环境变量比 CLI 参数更安全（令牌不会出现在进程列表中）
• MCP 配置文件可能包含令牌——请确保它们不会提交到版本控制中
• 考虑在生产环境中使用外部密钥管理
• 使用具有最低必要权限的范围受限令牌
• 定期轮换令牌以增强安全性
• 通过 Turso 控制面板监控令牌使用情况

示例：完整的 Turso 设置

1. 创建并配置数据库：

   # 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
   

2. 配置 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"
         ]
       }
     }
   }
   

3. 测试连接：

   # 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 禁用所有日志记录

2. 更新配置后，完全重启 Claude Desktop

3. 通过让 Claude 执行 SQL 查询来测试集成：

   Can you run this SQL query: SELECT 1 as test
   

📋 可用工具

• read-query - 执行经过安全验证的 SELECT 查询
• write-query - 执行支持事务的 INSERT/UPDATE/DELETE 操作
• create-table - 执行经过 DDL 安全检查的 CREATE TABLE
• alter-table - 修改表结构（ADD/RENAME/DROP）
• list-tables - 浏览数据库元数据和对象
• describe-table - 查看表架构和结构

📖 **详细 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 Node 版本选择方式。

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 项测试

🤝 贡献

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

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

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

🔗 链接

• Model Context Protocol
• MCP TypeScript SDK
• libSQL 文档
• Claude Desktop