SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingmcp-libsql

mcp-libsql

Security and management tools for libSQL databases.

Open website

About this tool

Purpose

mcp-libsql is a Model Context Protocol (MCP) server used to perform operations on libSQL databases, enabling Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients to securely access databases. It runs on Node and is written in TypeScript.

Main Capabilities

The project provides 6 core tools:

  • read-query: executes SELECT queries with security validation;
  • write-query: executes INSERT/UPDATE/DELETE operations with transaction support;
  • create-table: executes DDL operations such as CREATE TABLE with security measures;
  • alter-table: modifies table structures with support for ADD/RENAME/DROP operations;
  • list-tables: browses database metadata with filtering options;
  • describe-table: views table structures with support for multiple output formats.

In terms of security and reliability, the officially listed features include: multi-layered SQL injection protection and comprehensive security validation; connection pooling with health monitoring and automatic retries; transaction support with automatic rollback on errors; and comprehensive audit logging for security compliance (for security details, see docs/SECURITY.md).

In terms of developer experience: provides table-formatted output that is aligned and properly handles NULL; all operations display performance metrics; error messages are clear and carry actionable context; supports parameterized queries; provides a development mode with enhanced logging and hot reload.

In terms of test coverage, two sets of numbers appear in the repository: one place states "244 total tests (177 unit + 67 security), 100% pass rate"; another place under "Test Coverage" states 403 tests, covering edge cases, error scenarios, CLI parameters, authentication, and security validation.

Usage

Installation (global):

pnpm install -g @xexr/mcp-libsql

Local testing:

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

Prerequisites: pnpm (or npm) package manager, libSQL database (file or remote), Claude Desktop (for MCP integration). On supported platforms, macOS and Linux use native Node.js installation, while Windows can use native Node.js or WSL2 with Node.js. The documentation assumes global installation; if using a local build, replace "mcp-libsql" with "node dist/index.js".

Configuring the MCP server in Claude Desktop requires creating a configuration file according to the operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration example (macOS/Linux):

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"
{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": ["--url", "libsql://my-app-db-username.turso.io"]
    }
  }
}

The official recommendation is to prefer global installation because it automatically handles PATH. When using nvm for global installation on Windows, it is recommended to use wsl.exe -e(rather than just wsl.exe) to ensure commands are handled correctly.

Database authentication (for databases requiring credentials, such as Turso):

# 安装 Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# 登录
turso auth login

# 创建认证令牌
turso auth token create --name "mcp-libsql"

# 获取数据库 URL
turso db show your-database-name --url

Example of creating and configuring a database:

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

Points of caution given in the documentation: environment variables are more secure than CLI parameters (tokens will not appear in the process list); MCP configuration files may contain tokens, so be careful not to commit them to version control; for production environments, consider external secret management; use scoped tokens with least privilege; rotate tokens regularly; monitor token usage through the Turso console.

For file paths, it is recommended to use absolute paths to avoid path resolution issues. Database URL forms: for file databases, file:///absolute/path/to/database.db; for HTTP databases, http://hostname:port; for libSQL/Turso, libsql://your-database.turso.io. The Node.js path can be found using which node . Log mode description: the default file mode avoids JSON parsing errors in the MCP protocol;--log-mode console is used for development debugging;--log-mode both is used for full logging;--log-mode none Disable all logging. After updating the configuration, Claude Desktop must be fully restarted. You can test the integration by having Claude execute SELECT 1 as test to test the integration.

Use Cases

Suitable for scenarios where you need to query, write, create tables, and manage table schemas for local files or remote (such as Turso) libSQL databases in MCP clients such as Claude Desktop, Claude Code, and Cursor, and where there are requirements for security validation, connection reliability, and audit logging.

Limitations and Notes

Common issues include: build failures, Node.js version issues (on macOS, Claude Desktop may use an older version of Node.js by default), the server failing to start, tools being unavailable, JSON parsing errors, and database connection issues. The documentation states that the JSON parsing error has been resolved by default through --log-mode default file mode; this error is harmless and the tools still work. For complete troubleshooting, see docs/TROUBLESHOOTING.md. The project uses the MIT License. For detailed API documentation, see docs/API.md.

(The above content is compiled based on the repository's official description; features, fees, pricing, platforms, or performance information not provided in the materials are not yet available.)

Related tools

Browse category