项目简介

MCP libSQL 是一个实现了 Model Context Protocol (MCP) 的后端服务器，专门用于与 libSQL 数据库进行交互。它通过 MCP 协议将数据库操作能力作为工具暴露给支持 MCP 的 LLM 客户端（如 Claude Desktop）。这意味着您可以通过自然语言指令让 LLM 安全地访问、查询和管理您的 libSQL 数据库。

主要功能点

数据库连接与管理: 支持文件、HTTP 和 Turso 等多种 libSQL 数据库连接方式，提供连接池管理和自动重试。
安全的数据访问: 通过定义好的工具执行数据库操作，并内置多层安全校验，特别是针对 SQL 注入攻击的防护。
丰富的数据库工具: 提供了以下核心工具：
- 'read-query': 执行安全的 SELECT 查询，并格式化结果。
- 'write-query': 执行 INSERT, UPDATE, DELETE 操作，支持事务。
- 'create-table': 执行 CREATE TABLE DDL 语句，支持安全校验和事务。
- 'alter-table': 执行 ALTER TABLE DDL 语句，支持添加、重命名、删除列等操作，支持安全校验和事务。
- 'list-tables': 列出数据库中的表、视图、索引等对象，支持过滤和多种输出格式。
- 'describe-table': 获取指定表的详细结构信息，包括列、索引、外键等，支持多种输出格式。
性能监控: 每次工具执行都会报告操作的耗时。
错误处理与审计: 提供详细的日志记录，包括连接、查询、事务和错误信息，便于审计和问题排查。

安装步骤

确保您已安装 Node.js (推荐 20+) 和 npm 或 pnpm 包管理器。
打开终端，全局安装 MCP libSQL：
```
pnpm install -g @xexr/mcp-libsql
```
（或者使用 npm：'npm install -g @xexr/mcp-libsql'）
安装完成后，您可以在终端运行 'mcp-libsql -v' 来检查版本。

服务器配置（面向 MCP 客户端，例如 Claude Desktop）

MCP 客户端需要知道如何启动 MCP libSQL 服务器并传递必要的配置。通常，这通过客户端的配置文件完成。您需要指定 MCP libSQL 的可执行命令 ('command') 和启动参数 ('args')。

主要参数说明：

'--url <DATABASE_URL>': 必需，指定 libSQL 数据库的连接 URL。例如：
- 本地文件数据库：'file:///path/to/your/database.db'
- HTTP 数据库：'http://hostname:port'
- Turso 数据库：'libsql://your-db-name.turso.io'
'--auth-token <token>': 可选，为 Turso 或其他需要认证的数据库提供认证令牌。出于安全考虑，强烈推荐使用环境变量 'LIBSQL_AUTH_TOKEN' 来提供令牌，而不是直接在参数中。
'--min-connections <number>': 可选，连接池的最小连接数（默认为 1）。
'--max-connections <number>': 可选，连接池的最大连接数（默认为 10）。
'--connection-timeout <number>': 可选，连接获取超时时间（毫秒）（默认为 30000）。
'--query-timeout <number>': 可选，单次查询执行超时时间（毫秒）（默认为 30000）。
'--log-mode <mode>': 可选，日志输出模式：'file' (默认, 输出到文件)、'console' (输出到终端)、'both' (同时输出)、'none' (关闭日志)。
'--dev': 可选，启用开发模式，提供更详细的日志和热重载支持。

客户端配置文件示例（非实际代码，仅说明参数概念）：

{
  "mcpServers": {
    "mcp-libsql": {
      // 'command' 指定启动命令
      "command": "mcp-libsql", // 如果是全局安装
      // 或者 "command": "node", "args": ["/path/to/your/mcp-libsql/dist/index.js", ...] 如果是本地构建
      // 'args' 是一个字符串数组，包含传递给命令的参数
      "args": [
        "--url", "file:///path/to/your/database.db", // 数据库URL参数
        // 如果使用Turso等需要认证的数据库，且未使用环境变量，可以在此处添加
        // "--auth-token", "your-turso-auth-token" // 认证令牌参数（不推荐直接写在这里）
        // 其他可选参数...
        // "--max-connections", "15",
        // "--log-mode", "console"
      ]
      // 客户端可能还支持其他配置，如 cwd (工作目录) 等
    }
  }
}

重要提示： 配置完成后，请确保完全重启您的 MCP 客户端（如 Claude Desktop）。对于需要认证的数据库，强烈建议将 'LIBSQL_AUTH_TOKEN' 设置为环境变量，而不是作为命令行参数或直接写入配置文件。

基本使用方法

按照上述步骤安装 MCP libSQL。
在您的 MCP 客户端（如 Claude Desktop）中，根据客户端文档配置 MCP 服务器启动命令和数据库 URL。
配置完成后，通过客户端与 LLM 进行对话。您可以像与数据库专家交流一样，用自然语言请求 LLM 执行数据库操作。例如：
- "请帮我列出数据库中所有的表。" (List all tables in the database.)
- "查询 'users' 表中所有用户的名字和邮箱。" (Query the 'users' table for all users' names and emails.)
- "在 'products' 表中插入一条新产品记录：名字是'Widget A'，价格9.99。" (Insert a new product record into the 'products' table: name 'Widget A', price 9.99.)
- "修改 'orders' 表，给它添加一个叫做 'status' 的文本列。" (Alter the 'orders' table, add a text column named 'status'.)
- "显示 'customers' 表的结构。" (Show the structure of the 'customers' table.)
LLM 将使用 MCP libSQL 服务器提供的工具来执行您的请求，并将结果返回给您。

关键词

信息