연결 풀링과 트랜잭션을 지원하며, AI 클라이언트에서 안전하게 SQL 쿼리를 실행하고 테이블 생성 및 변경, libSQL 데이터베이스 스키마 조사가 가능합니다.
다른 이름 Xexr/mcp-libsql
- 스타
- 21
- Tools
- 6
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 22일
- 라이선스
- MIT
libSQL MCP란?
libSQL은(는) MCP server입니다. 연결 풀링과 트랜잭션을 지원하며, AI 클라이언트에서 안전하게 SQL 쿼리를 실행하고 테이블 생성 및 변경, libSQL 데이터베이스 스키마 조사가 가능합니다. 6개 도구를 제공합니다. 예: read-query, write-query, create-table.
프로젝트 README에서 생성된 요약
libSQL MCP server 정보
이 MCP server를 사용하면 AI 인터페이스에서 libSQL 데이터베이스를 직접 관리할 수 있습니다. 개발자는 Claude Desktop, Claude Code 또는 Cursor와 같은 클라이언트를 사용하여 파일 기반, HTTP 또는 Turso 데이터베이스와 상호작용할 수 있습니다. 이 서버는 SELECT 쿼리 실행, 트랜잭션 지원을 포함한 쓰기 작업 수행, 테이블 생성 및 수정을 통한 데이터베이스 스키마 관리 도구 세트를 제공합니다.
보안을 최우선으로 설계되었으며, 다층 SQL 인젝션 방지 기능과 67개의 보안 테스트를 통한 포괄적인 검증을 특징으로 합니다. 사용자는 환경 변수나 CLI 파라미터를 통해 URL과 인증 토큰을 제공함으로써 원격 Turso 인스턴스에 연결할 수 있습니다. 또한 개발 및 운영 환경에서 안정적인 데이터베이스 상호작용을 보장하기 위해 연결 풀링, 자동 재시도 로직 및 감사 로그 기능을 포함하고 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
libSQL MCP 도구 6
README에서 감지됨read-querywrite-querycreate-tablealter-tablelist-tablesdescribe-table
| read-query | — | |
| write-query | — | |
| create-table | — | |
| alter-table | — | |
| list-tables | — | |
| describe-table | — |
구성
LIBSQL_AUTH_TOKEN
| 이름 | 설명 | 유형 |
|---|---|---|
| LIBSQL_AUTH_TOKEN | — |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기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
- File databases:
- Node.js path: Use
which nodeto find your Node.js installation path - Working directory: Set
cwdto ensure relative paths work correctly - Authentication: For Turso databases, use environment variables for secure token handling
- Logging modes:
- Default
filemode prevents JSON parsing errors in MCP protocol - Use
--log-mode consolefor development debugging - Use
--log-mode bothfor comprehensive logging - Use
--log-mode noneto disable all logging
- Default
-
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 buildwas run anddist/index.jsexists - 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.
🔗 Links
libSQL MCP 질문
libSQL MCP는 어떤 도구를 제공하나요?
6개 도구를 제공합니다. 예: read-query, write-query, create-table, alter-table, list-tables.
libSQL MCP server는 어떤 도구를 제공하나요?
read-query, write-query, create-table, alter-table, list-tables, describe-table 등 총 6개의 도구를 제공합니다.
Turso 데이터베이스 인증은 어떻게 하나요?
LIBSQL_AUTH_TOKEN 환경 변수(권장) 또는 --auth-token CLI 파라미터를 통해 libSQL 인증 토큰을 제공하면 됩니다.
트랜잭션을 지원하나요?
네, 쓰기 작업은 트랜잭션을 지원하며 오류 발생 시 자동으로 롤백됩니다.
SQL 인젝션을 방지할 수 있나요?
네, 보안 검증을 통한 다층 SQL 인젝션 방지 기능을 적용하고 있으며 67개의 보안 테스트를 거쳤습니다.