MCP libSQL by xexr

xexr による MCP libSQL

libSQL データベース操作用の Model Context Protocol（MCP）サーバーです。Claude Desktop、Claude Code、Cursor、その他の MCP 対応クライアントから、安全にデータベースへアクセスできます。

Node 上で動作し、TypeScript で記述されています。

🔧 クイックスタート

1. インストール：

   pnpm install -g @xexr/mcp-libsql
   

2. ローカルでテスト：

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

3. Claude Desktop を設定： Node.js のパスとデータベース URL を指定します（以下の設定例を参照）。

🚀 ステータス

✅ 完全なデータベース管理機能 - 6 つのコアツールすべてを実装し、テスト済みです
✅ 包括的なセキュリティ検証 - あらゆるインジェクションベクトルを対象とする 67 件のセキュリティテストを実施しています
✅ 広範なテストカバレッジ - 合計 244 件のテスト（ユニットテスト 177 件＋セキュリティテスト 67 件）を実施し、合格率は 100％です
✅ 本番環境へのデプロイを検証済み - MCP クライアントで正常に動作します
✅ 堅牢なエラー処理 - 接続の再試行、グレースフルデグラデーション、監査ログに対応しています

🛠️ 機能

利用可能なツール

• read-query：包括的なセキュリティ検証を行い、SELECT クエリを実行します
• write-query：トランザクションに対応した INSERT／UPDATE／DELETE 操作を実行します
• create-table：セキュリティ対策を施したテーブル作成用の DDL 操作を実行します
• alter-table：テーブル構造を変更します（ADD／RENAME／DROP 操作）
• list-tables：フィルタリングオプションを使用して、データベースのメタデータを参照します
• describe-table：複数の出力形式でテーブルスキーマを確認します

セキュリティと信頼性

• 多層的な SQL インジェクション防止機能と包括的なセキュリティ検証
• 接続プーリングとヘルスモニタリング、自動再試行ロジック
• トランザクション対応とエラー発生時の自動ロールバック
• セキュリティコンプライアンスに対応する包括的な監査ログ

🔐 セキュリティの詳細： 包括的なセキュリティ機能とテストについては、docs/SECURITY.md を参照してください。

開発者エクスペリエンス

• 適切な配置と NULL 処理に対応した見やすいテーブル形式
• すべての操作でパフォーマンス指標を表示
• 実行可能な対処方法を含むわかりやすいエラーメッセージ
• 安全なデータ処理のためのパラメーター化クエリ対応
• 拡張ロギングとホットリロードに対応した開発モード

📋 前提条件

• Node.js 20 以降
• pnpm（または npm）パッケージマネージャー
• libSQL データベース（ファイルベースまたはリモート）
• Claude Desktop（MCP 連携用）

プラットフォーム要件

• macOS：ネイティブの Node.js インストール
• Linux：ネイティブの Node.js インストール
• Windows：ネイティブの Node.js インストール、または Node.js をインストールした WSL2

🔧 インストール

# 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

🚀 使い方

ローカルテスト

以下ではグローバルインストールを前提としています。ローカルビルドを使用する場合は、「mcp-libsql」を「node dist/index.js」に置き換えてください。

# 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 との連携

お使いのオペレーティングシステムに応じて、Claude Desktop で MCP サーバーを設定します。

macOS の設定

1. ~/Library/Application Support/Claude/claude_desktop_config.json に設定ファイルを作成します。

グローバルインストール

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///Users/username/database.db"
      ]
    }
  }
}

ローカルビルドをインストールする場合の代替設定：

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-libsql/dist/index.js",
        "--url", 
        "file:///Users/username/database.db"
      ],
    }
  }
}

nvm lts を使って 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",
      ],
    }
  }
}

重要：グローバルインストールでは PATH が自動的に処理されるため、この方法を推奨します。

Linux の設定

1. ~/.config/Claude/claude_desktop_config.json に設定ファイルを作成します。

グローバルインストール

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///home/username/database.db"
      ]
    }
  }
}

ローカルビルドをインストールする場合の代替設定：

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/home/username/projects/mcp-libsql/dist/index.js",
        "--url",
        "file:///home/username/database.db"
      ],
    }
  }
}

Windows（WSL2）の設定

1. %APPDATA%\Claude\claude_desktop_config.json に設定ファイルを作成します。

グローバルインストール

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

ローカルビルドをインストールする場合の代替設定：

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "/home/username/projects/mcp-libsql/dist/index.js --url file:///home/username/database.db",
      ]
    }
  }
}

nvm を使って Node をグローバルインストールする場合の代替設定

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "source ~/.nvm/nvm.sh && mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

重要：適切なコマンド処理を確実に行い、Windows でサーバーコマンドを受信する際の問題を避けるため、wsl.exe だけではなく wsl.exe -e を使用してください。

データベース認証

Turso（およびその他の認証情報が必要な）データベースでは、認証トークンが必要です。安全に提供する方法は2つあります。

以下ではグローバルインストールの例を示しています。環境に合わせて調整してください

方法1：環境変数（推奨）

環境変数を使用してClaude Desktopを設定する（macOS/Linuxの例）：

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io"
      ]
    }
  }
}

方法2：CLIパラメーター

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io",
        "--auth-token",
        "your-turso-auth-token-here"
      ]
    }
  }
}

Turso認証トークンの取得

1. Turso CLIをインストールします：

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

2. Tursoにログインします：

   turso auth login
   

3. 認証トークンを作成します：

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

4. データベースURLを取得します：

   turso db show your-database-name --url
   

セキュリティのベストプラクティス

• 環境変数はCLIパラメーターより安全です（トークンがプロセス一覧に表示されません）
• MCP設定ファイルにトークンが含まれることがあります。バージョン管理にコミットされないようにしてください
• 本番環境では外部のシークレット管理の利用を検討してください
• 必要最小限の権限を持つスコープ付きトークンを使用してください
• セキュリティを強化するため、トークンを定期的にローテーションしてください
• Tursoダッシュボードでトークンの使用状況を監視してください

例：Tursoの完全なセットアップ

1. データベースを作成して設定します：

   # 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
   

2. 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 locally first
   mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console
   

設定に関する注意事項

• ファイルパス：パス解決の問題を避けるため、絶対パスを使用してください
• データベースURL：
  • ファイルデータベース：file:///absolute/path/to/database.db
  • HTTPデータベース：http://hostname:port
  • libSQL/Turso：libsql://your-database.turso.io
• Node.jsのパス：which nodeを使用して、Node.jsのインストール先のパスを確認してください
• 作業ディレクトリ：相対パスが正しく機能するように、cwdを設定してください
• 認証：Tursoデータベースでは、安全にトークンを扱うために環境変数を使用してください
• ログモード：
  • デフォルトのfileモードでは、MCPプロトコルでJSONの解析エラーが発生しません
  • 開発時のデバッグには--log-mode consoleを使用してください
  • 包括的なログ記録には--log-mode bothを使用してください
  • すべてのログ記録を無効にするには--log-mode noneを使用してください

2. 設定を更新した後、Claude Desktopを完全に再起動します

3. ClaudeにSQLクエリの実行を依頼して、連携をテストします：

   Can you run this SQL query: SELECT 1 as test
   

📋 利用可能なツール

• read-query - セキュリティ検証付きでSELECTクエリを実行します
• write-query - トランザクションをサポートしてINSERT/UPDATE/DELETEを実行します
• create-table - DDLセキュリティを備えたCREATE TABLEを実行します
• alter-table - テーブル構造を変更します（ADD/RENAME/DROP）
• list-tables - データベースのメタデータとオブジェクトを参照します
• describe-table - テーブルのスキーマと構造を確認します

📖 APIドキュメントの詳細： 入出力の例とパラメーターについては、docs/API.mdをご覧ください。

🧪 テスト

# 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

テストカバレッジ：エッジケース、エラーシナリオ、CLI引数、認証、包括的なセキュリティ検証を含む、すべての機能を対象とした403件のテスト。

⚠️ よくある問題

1. ビルドの失敗

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

2. Node.jsのバージョンに関する問題（macOS）

SyntaxError: Unexpected token '??='

問題：Claude Desktopが、必要な機能セットに対応していない古いバージョンのNode.jsをシステム上でデフォルトとして使用することがあります。

解決策：上記のグローバルインストールとnvmによるNode.js選択の方法を使用してください。

3. サーバーが起動しない

• グローバルインストールの場合：pnpm install -g @xexr/mcp-libsql
• ローカルインストールの場合：pnpm buildを実行済みで、dist/index.jsが存在することを確認してください
• ローカルでテストする場合：mcp-libsql --url file:///tmp/test.db
• 設定を変更した後、Claude Desktopを再起動してください

4. ツールを利用できない

• データベースURLにアクセスできることを確認してください
• Claude Desktopのログで接続エラーを確認してください
• シンプルなファイルデータベースでテストしてください：file:///tmp/test.db

5. JSON 解析エラー（解決済み）

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

解決済み：この問題は標準出力へのコンソールログ出力が原因です。--log-mode オプションのデフォルトが file モードになり、この問題が発生しなくなりました。これらのエラーが表示される場合は、デフォルトの --log-mode file を使用していること、または --log-mode を指定していないことを確認してください。このエラーは無害であり、コンソールログ出力を使用したい場合でも、ツールは引き続き動作します。

6. データベース接続の問題

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

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

🔧 トラブルシューティングの完全ガイド： あらゆる問題の詳しい解決方法については、docs/TROUBLESHOOTING.md をご覧ください。

🏗️ アーキテクチャ

TypeScript と最新の Node.js パターンを使用して構築されています。

• 接続プーリング：ヘルスモニタリングと再試行ロジックを備えています
• ツールベースのアーキテクチャ：一貫した検証とエラー処理を備えています
• セキュリティ優先の設計：多層的な入力検証を行います
• 包括的なテスト：あらゆるシナリオを網羅する 244 件のテストを実施しています

🤝 コントリビュート

1. TypeScript の strict モードと既存のコードパターンに従ってください
2. 新機能にはテストを作成してください
3. セキュリティ対策を維持してください
4. ドキュメントを更新してください

開発： pnpm dev • ビルド： pnpm build • テスト： pnpm test

📄 ライセンス

MIT ライセンスです。詳細については LICENSE ファイルをご覧ください。

🔗 リンク

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