MCP Libsql

xexr的MCP libSQL

用于libSQL数据库操作的模型上下文协议（MCP）服务器，通过Claude Desktop、Claude Code、Cursor和其他MCP兼容客户端提供安全的数据库访问。

在Node上运行，用TypeScript编写

🔧 快速开始

1. 安装：

   pnpm install -g @xexr/mcp-libsql

1. 本地测试：

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

1. 配置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配置

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进行节点全局安装的替代配置

{
  "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 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认证令牌

1. 安装Turso CLI：

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

1. 登录Turso：

   turso auth login

1. 创建身份验证令牌：

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

1. 获取您的数据库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

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

1. 测试连接：

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

1. 重新启动克劳德桌面 完全更新配置后

1. 测试集成 通过让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个测试涵盖所有场景

🤝 贡献

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

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

📄 许可证

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

🔗 链接

• 模型上下文协议
• MCP TypeScript SDK
• libSQL文档
• 克劳德桌面版