MCP libSQL by xexr

A Model Context Protocol (MCP) server for libSQL database operations, providing secure database access through Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients.

Runs on Node, written in TypeScript

🔧 Quick Start

1. Install:

   pnpm install -g @xexr/mcp-libsql
   

2. Test locally:

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

3. Configure Claude Desktop with your Node.js path and database URL (see configuration examples below)

🚀 Status

✅ Complete database management capabilities - All 6 core tools implemented and tested
✅ Comprehensive security validation - 67 security tests covering all injection vectors
✅ Extensive test coverage - 244 total tests (177 unit + 67 security) with 100% pass rate
✅ Production deployment verified - Successfully working with MCP clients
✅ Robust error handling - Connection retry, graceful degradation, and audit logging

🛠️ Features

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 table creation with security measures
• alter-table: Table structure modifications (ADD/RENAME/DROP operations)
• list-tables: Database metadata browsing with filtering options
• describe-table: Table schema inspection with multiple output formats

Security & Reliability

• Multi-layer SQL injection prevention with comprehensive security validation
• Connection pooling with health monitoring and automatic retry logic
• Transaction support with automatic rollback on errors
• Comprehensive audit logging for security compliance

🔐 Security details: See docs/SECURITY.md for comprehensive security features and testing.

Developer Experience

• Beautiful table formatting with proper alignment and NULL handling
• Performance metrics displayed for all operations
• Clear error messages with actionable context
• Parameterized query support for safe data handling
• Development mode with enhanced logging and hot reload

📋 Prerequisites

• Node.js 20+
• pnpm (or npm) package manager
• libSQL database (file-based or remote)
• Claude Desktop (for MCP integration)

Platform Requirements

• macOS: Native Node.js installation
• Linux: Native Node.js installation
• Windows: Native Node.js installation or WSL2 with Node.js installation

🔧 Installation

# Use your package manager of choice, e.g. npm, pnpm, bun etc

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

# ...or build from the repository
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # Install dependencies
pnpm build # Build the project
node dist/index.js -v  # check version

🚀 Usage

Local Testing

Global installation assumed below, replace "mcp-libsql" with "node dist/index.js" if using local build

# Test with file database (default: file-only logging)
mcp-libsql --url file:///tmp/test.db

# Test with HTTP database
mcp-libsql --url http://127.0.0.1:8080

# Test with Turso database (environment variable, alternatively export the env var)
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# Test with Turso database (CLI parameter)
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# Development mode with console logging
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# Test with different logging modes
mcp-libsql --url --log-mode both file:///tmp/test.db

Claude Desktop Integration

Configure the MCP server in Claude Desktop based on your operating system:

macOS Configuration

1. Create configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

Global install

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

Alternative configuration for local build installation:

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

Alternative configuration for global install using nvm lts for 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",
      ],
    }
  }
}

Important: The global installation method is recommended as it handles PATH automatically.

Linux Configuration

1. Create configuration file at ~/.config/Claude/claude_desktop_config.json:

Global install

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

Alternative configuration for local build installation:

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

Windows (WSL2) Configuration

1. Create configuration file at %APPDATA%\Claude\claude_desktop_config.json:

Global install

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

Alternative configuration for local build installation:

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

Alternative configuration for global install using nvm for node

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

Important: Use wsl.exe -e (not just wsl.exe) to ensure proper command handling and avoid issues with server command reception on Windows.

Database Authentication

For Turso (and other credentialed) databases, you'll need an authentication token. There are two secure ways to provide it:

Global installation shown below, adjust accordingly for your setup

Method 1: Environment Variable (Recommended)

Configure Claude Desktop with environment variable (macOS/Linux example):

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

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

Method 2: CLI Parameter

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

Getting Your Turso Auth Token

1. Install Turso CLI:

   curl -sSfL https://get.tur.so/install.sh | bash
   

2. Login to Turso:

   turso auth login
   

3. Create an auth token:

   turso auth token create --name "mcp-libsql"
   

4. Get your database URL:

   turso db show your-database-name --url
   

Security Best Practices

• Environment variables are safer than CLI parameters (tokens won't appear in process lists)
• MCP config files may contain tokens - ensure they're not committed to version control
• Consider using external secret management for production environments
• Use scoped tokens with minimal required permissions
• Rotate tokens regularly for enhanced security
• Monitor token usage through Turso dashboard

Example: Complete Turso Setup

1. Create and configure database:

   # Create database
   turso db create my-app-db
   
   # Get database URL
   turso db show my-app-db --url
   # Output: libsql://my-app-db-username.turso.io
   
   # Create auth token
   turso auth token create --name "mcp-libsql-token"
   # Output: your-long-auth-token-string
   

2. Configure 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. Test the connection:

   # Test locally first
   mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console
   

Configuration Notes

• File paths: Use absolute paths to avoid path resolution issues
• Database URLs:
  • File databases: file:///absolute/path/to/database.db
  • HTTP databases: http://hostname:port
  • libSQL/Turso: libsql://your-database.turso.io
• Node.js path: Use which node to find your Node.js installation path
• Working directory: Set cwd to ensure relative paths work correctly
• Authentication: For Turso databases, use environment variables for secure token handling
• Logging modes:
  • Default file mode prevents JSON parsing errors in MCP protocol
  • Use --log-mode console for development debugging
  • Use `--log-mode b

---