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

Categories

Current Category: libsql

mcp-libsql

mcp-svelte-docs

mcp-turso