MCP Libsql

🚀 xexr的MCP libSQL

MCP libSQL 是一个用于 libSQL 数据库操作的模型上下文协议（MCP）服务器，它支持通过 Claude Desktop、Claude Code、Cursor 等兼容 MCP 的客户端安全地访问数据库。该项目基于 Node.js 运行，使用 TypeScript 编写。

🚀 快速开始

安装

pnpm install -g @xexr/mcp-libsql

本地测试

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

配置 Claude Desktop

在 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：修改表结构（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 或在 WSL2 中安装 Node.js。

安装步骤

# 使用你选择的包管理器，如 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 进行全局安装的替代配置

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

{
  "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 操作，并采取安全措施。
• 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 节点选择方法。

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

🔧 技术细节

项目状态

✅ 完整的数据库管理能力 - 所有 6 个核心工具都已实现并通过测试。
✅ 全面的安全验证 - 进行了 67 项安全测试，涵盖了所有可能的注入向量。
✅ 广泛的测试覆盖 - 总计 244 项测试（177 项单元测试 + 67 项安全测试），通过率达到 100%。
✅ 生产部署验证 - 已经在实际环境中与 MCP 客户端成功配合使用。
✅ 强大的错误处理 - 支持连接重试、优雅降级和审计日志记录，确保系统的稳定性和可靠性。

安全与可靠性

• 多层 SQL 注入防护：通过全面的安全验证机制，对输入的 SQL 查询进行严格的检查和过滤，有效防止 SQL 注入攻击。
• 连接池：具备健康监控和自动重试逻辑，能够实时监测数据库连接的状态，当连接出现问题时，自动进行重试，确保系统的高可用性。
• 事务支持：在执行 INSERT/UPDATE/DELETE 等操作时，支持事务处理，并在出现错误时自动回滚，保证数据的一致性和完整性。
• 全面的审计日志：记录所有与数据库交互的操作，包括操作的时间、用户、内容等信息，方便进行安全审计和合规性检查。

开发者体验

• 美观的表格格式：在显示查询结果时，采用了美观的表格格式，具备正确的对齐和 NULL 处理，提高了数据的可读性。
• 性能指标展示：在执行所有操作时，都会显示相应的性能指标，如查询执行时间、资源消耗等，帮助开发者优化代码和提高系统性能。
• 清晰的错误信息：当出现错误时，会提供清晰的错误信息，并附带可操作的上下文，方便开发者快速定位和解决问题。
• 参数化查询支持：支持参数化查询，能够安全地处理用户输入的数据，避免 SQL 注入风险。
• 开发模式：提供开发模式，增强日志记录和热重载功能，方便开发者在开发过程中进行调试和测试。

架构设计

• 连接池：采用连接池技术，具备健康监控和重试逻辑，能够有效管理数据库连接，提高系统的性能和稳定性。
• 工具基于架构：采用工具基于架构，每个工具都有一致的验证和错误处理机制，方便开发者进行扩展和维护。
• 安全优先设计：在设计过程中，将安全放在首位，采用多层输入验证机制，确保系统的安全性和可靠性。
• 全面测试：进行了全面的测试，包括单元测试、安全测试等，共计 244 项测试，覆盖了所有可能的场景，确保系统的质量和稳定性。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔗 相关链接

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