MCP Libsql

🚀 MCP libSQL by xexr

A Model Context Protocol (MCP) server for libSQL database operations, offering secure database access via Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients. It runs on Node and is 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

Configure Claude Desktop with your Node.js path and database URL (refer to the configuration examples below).

✨ Features

Available Tools

• read-query: Execute SELECT queries with comprehensive security validation.
• write-query: Perform INSERT/UPDATE/DELETE operations with transaction support.
• create-table: Conduct DDL operations for table creation with security measures.
• alter-table: Modify table structure (ADD/RENAME/DROP operations).
• list-tables: Browse database metadata with filtering options.
• describe-table: Inspect table schema with multiple output formats.

Security & Reliability

• Multi-layer SQL injection prevention: Implement comprehensive security validation.
• Connection pooling: Feature health monitoring and automatic retry logic.
• Transaction support: Provide automatic rollback on errors.
• Comprehensive audit logging: Ensure security compliance.

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

Developer Experience

• Beautiful table formatting: Ensure proper alignment and NULL handling.
• Performance metrics: Display metrics for all operations.
• Clear error messages: Provide actionable context.
• Parameterized query support: Enable safe data handling.
• Development mode: Offer enhanced logging and hot reload.

📦 Installation

# Use your preferred package manager, 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 Examples

Local Testing

The following assumes a global installation. Replace "mcp-libsql" with "node dist/index.js" if using a local build.

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

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

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

# Test with a Turso database (using a 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 according to your operating system:

macOS Configuration

1. Create a 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 automatically handles the PATH.

Linux Configuration

1. Create a 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 a 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 need an authentication token. There are two secure ways to provide it:

The following shows a global installation; adjust according to your setup.

Method 1: Environment Variable (Recommended)

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

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 the Turso CLI:

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

2. Log in 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 the Turso dashboard.

Example: Complete Turso Setup

1. Create and configure the database:

   # Create the database
   turso db create my-app-db
   
   # Get the database URL
   turso db show my-app-db --url
   # Output: libsql://my-app-db-username.turso.io
   
   # Create an 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:
  • The default file mode prevents JSON parsing errors in the MCP protocol.
  • Use --log-mode console for development debugging.
  • Use --log-mode both for comprehensive logging.
  • Use --log-mode none to disable all logging.

2. Restart Claude Desktop completely after updating the configuration.

3. Test the integration by asking Claude to run SQL queries:

   Can you run this SQL query: SELECT 1 as test
   

📚 Documentation

Available Tools

• read-query: Execute SELECT queries with security validation.
• write-query: Perform INSERT/UPDATE/DELETE operations with transaction support.
• create-table: Create tables with DDL security.
• alter-table: Modify table structure (ADD/RENAME/DROP).
• list-tables: Browse database metadata and objects.
• describe-table: Inspect table schema and structure.

📖 Detailed API documentation: Refer to docs/API.md for complete input/output examples and parameters.

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run a specific test file
pnpm test security-verification

# Lint the code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Perform type checking
pnpm typecheck

Test Coverage: 403 tests cover all functionality, including edge cases, error scenarios, CLI arguments, authentication, and comprehensive security validation.

Common Issues

1. Build Failures

# Clean and rebuild
rm -rf dist node_modules
pnpm install && pnpm build

2. Node.js Version Issues (macOS)

SyntaxError: Unexpected token '??='

Problem: Claude Desktop may default to using an older Node.js version on your system, which doesn't support the required feature set.

Solution: Use the global installation and nvm node selection method described above.

3. Server Won't Start

• For global installation: pnpm install -g @xexr/mcp-libsql
• For local installation: Ensure pnpm build was run and dist/index.js exists.
• Test locally: mcp-libsql --url file:///tmp/test.db
• Restart Claude Desktop after configuration changes.

4. Tools Not Available

• Verify that the database URL is accessible.
• Check Claude Desktop logs for connection errors.
• Test with a simple file database: file:///tmp/test.db

5. JSON Parsing Errors (Resolved)

Expected ',' or ']' after array element in JSON

Resolved: This issue is caused by stdout console logging. The --log-mode option now defaults to file mode, which prevents this issue. If you encounter these errors, ensure you're using the default --log-mode file or not specifying --log-mode at all. Note that the error is harmless, and the tool will still work if you want console logging.

6. Database Connection Issues

# Test database connectivity
sqlite3 /tmp/test.db "SELECT 1"

# Fix permissions
chmod 644 /path/to/database.db

🔧 Full troubleshooting guide: See docs/TROUBLESHOOTING.md for detailed solutions to all issues.

Architecture

Built with TypeScript and modern Node.js patterns:

• Connection pooling: Features health monitoring and retry logic.
• Tool-based architecture: Ensures consistent validation and error handling.
• Security-first design: Implements multi-layer input validation.
• Comprehensive testing: Includes 244 tests covering all scenarios.

Contributing

1. Follow TypeScript strict mode and existing code patterns.
2. Write tests for new features.
3. Maintain security measures.
4. Update documentation.

Development: pnpm dev • Build: pnpm build • Test: pnpm test

📄 License

This project is under the MIT License. See the LICENSE file for details.

🔗 Links

• Model Context Protocol
• MCP TypeScript SDK
• libSQL Documentation
• Claude Desktop