🚀 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 Desktop

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

✨ 主要特性

可用工具

• 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处理。
• 显示所有操作的性能指标。
• 提供带有可操作上下文的清晰错误消息。
• 支持参数化查询，确保数据安全处理。
• 具备增强日志记录和热重载功能的开发模式。

📦 安装指南

# 使用你选择的包管理器，例如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配置

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. 创建并配置数据库

   # 创建数据库
   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
   

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. 测试连接

   # 先进行本地测试
   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。

🔧 技术细节

测试

# 运行所有测试
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选择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. 数据库连接问题

# 测试数据库连接性
sqlite3 /tmp/test.db "SELECT 1"

# 修复权限
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 文件。

🔗 链接

• 模型上下文协议
• MCP TypeScript SDK
• libSQL文档
• Claude Desktop