MCP libSQL

You run a secure MCP server for libSQL that lets you access and manage your databases from MCP-compatible clients like Claude Desktop, Claude Code, and Cursor. This server focuses on safe, authenticated database operations with robust error handling, auditing, and multi-tool support so you can build reliable data workflows across your apps.

How to use

Connect to a local or remote libSQL database via an MCP client to perform read and write operations, manage tables, and browse metadata. Start the MCP server and point your client to a URL you control, then use the client’s MCP protocol to issue queries through the server. For troubleshooting and development, run in development mode to see enhanced logs, and use a file-based database for quick local testing.

How to install

Prerequisites you need before installation:

• Node.js 20+

• pnpm (or npm) as your package manager

• libSQL database (file-based or remote)

• Claude Desktop for MCP integration

# Install globally
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v

# Build from source (if you prefer local build)
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install
pnpm build
node dist/index.js -v

Configuration examples for Claude Desktop

Configure the MCP server in Claude Desktop for your operating system. The following examples show how to wire up the server using common installation paths.

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///Users/username/database.db"
      ]
    }
  }
}

Alternative local build configuration for Claude Desktop

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-libsql/dist/index.js",
        "--url", 
        "file:///Users/username/database.db"
      ],
    }
  }
}

Global install with NVM (macOS/Linux) for Claude Desktop

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "zsh",
      "args": [
        "-c",
        "source ~/.nvm/nvm.sh && nvm use --lts > /dev/null && mcp-libsql --url file:///Users/username/database.db",
      ],
    }
  }
}

Linux configuration for Claude Desktop

Create the configuration file at the Linux path shown.

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///home/username/database.db"
      ]
    }
  }
}

Windows (WSL2) configuration

Create the configuration file at the Windows path shown.

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

Database authentication (Turso and other credentialed databases)

You can provide an authentication token securely via environment variables or as a CLI parameter. The recommended approach is to set the environment variable in your environment and reference it in your configuration.

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io"
      ]
    }
  }
}

Security and tokens note

Environment variables are safer than passing tokens on the command line. Ensure token-bearing configuration files are not committed to version control and consider external secret management in production.

Testing the integration

Test the connection locally first by starting the MCP server with a file database and then run queries through your MCP client.

Available tools

read-query

Execute SELECT queries with comprehensive security validation

write-query

INSERT/UPDATE/DELETE operations with transaction support

create-table

DDL operations for creating tables with security measures

alter-table

Modify table structure (ADD/RENAME/DROP) with security checks

list-tables

Browse database metadata with filtering options

describe-table

Inspect table schema with multiple output formats