xexr/mcp-libsql

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:**
2. **Test locally:**
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**
🚀 **Usage**
**Local Testing**
Global installation assumed below, replace "mcp-libsql" with "node dist/index.js" if using local build
**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**
**Alternative configuration for local build installation:**
**Alternative configuration for global install using nvm lts for node**
**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**
**Alternative configuration for local build installation:**
**Windows (WSL2) Configuration**
1. **Create configuration file** at %APPDATA%\Claude\claude_desktop_config.json:
**Global install**
**Alternative configuration for local build installation:**
**Alternative configuration for global install using nvm for node**
**Important**: Use wsl.exe -e (not just wsl.exe) to ensure proper command handling and avoid issues with server command reception on Windows.