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

Install:
```
pnpm install -g @xexr/mcp-libsql
```

Test locally:

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

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

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

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

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

Install Turso CLI:

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

Login to Turso:
```
turso auth login
```

Create an auth token:

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

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

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

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"
      ]
    }
  }
}

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 both for comprehensive logging
- Use --log-mode none to disable all logging

Restart Claude Desktop completely after updating the configuration
Test the integration by asking Claude to run SQL queries:
```
Can you run this SQL query: SELECT 1 as test
```

📋 Available Tools

read-query - Execute SELECT queries with security validation
write-query - INSERT/UPDATE/DELETE with transaction support
create-table - CREATE TABLE 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: See 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 specific test file
pnpm test security-verification

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

Test Coverage: 403 tests covering 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 global installation and nvm node selection method shown 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 config changes

4. Tools Not Available

Verify database URL is accessible
Check Claude Desktop logs for connection errors
Test with 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 see these errors, ensure you're using the default --log-mode file or not specifying --log-mode at all. Note, the error is harmless, and the tool will still work with it if you wish to have 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 with health monitoring and retry logic
Tool-based architecture with consistent validation and error handling
Security-first design with multi-layer input validation
Comprehensive testing with 244 tests covering all scenarios

🤝 Contributing

Follow TypeScript strict mode and existing code patterns
Write tests for new features
Maintain security measures
Update documentation

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

📄 License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.claude/commands		.claude/commands
.github/workflows		.github/workflows
docs		docs
plans/mcp-libsql-server		plans/mcp-libsql-server
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
eslint.config.js		eslint.config.js
nodemon.json		nodemon.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

Xexr/mcp-libsql

Folders and files

Latest commit

History

Repository files navigation

MCP libSQL by xexr

🔧 Quick Start

🚀 Status

🛠️ Features

Available Tools

Security & Reliability

Developer Experience

📋 Prerequisites

Platform Requirements

🔧 Installation

🚀 Usage

Local Testing

Claude Desktop Integration

macOS Configuration

Linux Configuration

Windows (WSL2) Configuration

Database Authentication

Method 1: Environment Variable (Recommended)

Method 2: CLI Parameter

Getting Your Turso Auth Token

Security Best Practices

Example: Complete Turso Setup

Configuration Notes

📋 Available Tools

🧪 Testing

⚠️ Common Issues

1. Build Failures

2. Node.js Version Issues (macOS)

3. Server Won't Start

4. Tools Not Available

5. JSON Parsing Errors (Resolved)

6. Database Connection Issues

🏗️ Architecture

🤝 Contributing

📄 License

🔗 Links

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages