MCP Libsql

🚀 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を設定してください（以下の設定例を参照）。

✨ 主な機能

利用可能なツール

• 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処理を備えた美しいテーブル形式
• すべての操作に対して表示されるパフォーマンスメトリクス
• 実行可能なコンテキストを持つ明確なエラーメッセージ
• 安全なデータ処理のためのパラメータ化クエリサポート
• 拡張ロギングとホットリロードを備えた開発モード

📦 インストール

# 好みのパッケージマネージャーを使用します。例: npm、pnpm、bunなど

# グローバルにインストール
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # バージョンを確認

# ...またはリポジトリからビルド
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # 依存関係をインストール
pnpm build # プロジェクトをビルド
node dist/index.js -v  # バージョンを確認

💻 使用例

基本的な使用法

ローカルテスト

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

# ファイルデータベースでテスト（デフォルト: ファイルのみのロギング）
mcp-libsql --url file:///tmp/test.db

# HTTPデータベースでテスト
mcp-libsql --url http://127.0.0.1:8080

# Tursoデータベースでテスト（環境変数、または環境変数をエクスポート）
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# Tursoデータベースでテスト（CLIパラメータ）
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# コンソールロギングを使用した開発モード
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# 異なるロギングモードでテスト
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を使用したグローバルインストールの代替設定

{
  "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を使用したグローバルインストールの代替設定

{
  "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 -e（単なるwsl.exeではなく）を使用してください。

データベース認証

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. データベースを作成して構成する:

   # データベースを作成
   turso db create my-app-db
   
   # データベースURLを取得
   turso db show my-app-db --url
   # 出力: libsql://my-app-db-username.turso.io
   
   # 認証トークンを作成
   turso auth token create --name "mcp-libsql-token"
   # 出力: 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. 接続をテストする:

   # まずローカルでテスト
   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を参照してください。

🔧 技術詳細

このプロジェクトはTypeScriptと最新のNode.jsパターンを使用して構築されています。

• ヘルスモニタリングとリトライロジックを備えたコネクションプーリング
• 一貫した検証とエラー処理を備えたツールベースのアーキテクチャ
• 多層入力検証を備えたセキュリティ重視の設計
• すべてのシナリオをカバーする244のテストを備えた包括的なテスト

🧪 テスト

# すべてのテストを実行
pnpm test

# ウォッチモードでテストを実行
pnpm test:watch

# カバレッジ付きでテストを実行
pnpm test:coverage

# 特定のテストファイルを実行
pnpm test security-verification

# コードをリント
pnpm lint

# リントの問題を修正
pnpm lint:fix

# 型チェック
pnpm typecheck

テストカバレッジ: エッジケース、エラーシナリオ、CLI引数、認証、および包括的なセキュリティ検証を含むすべての機能をカバーする403のテストがあります。

⚠️ 一般的な問題と解決策

1. ビルド失敗

# クリーンして再ビルド
rm -rf dist node_modules
pnpm install && pnpm build

2. Node.jsバージョンの問題 (macOS)

SyntaxError: Unexpected token '??='

問題: Claude Desktopは、システムで古いNode.jsバージョンをデフォルトで使用する場合があり、必要な機能セットをサポートしていません。

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

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

解決済み: この問題はstdoutコンソールロギングによって引き起こされます。--log-modeオプションは現在、この問題を防止するfileモードがデフォルトになっています。これらのエラーが表示された場合は、デフォルトの--log-mode fileを使用するか、--log-modeをまったく指定しないようにしてください。このエラーは無害であり、コンソールロギングを行いたい場合はツールは引き続き機能します。

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

# データベースの接続性をテスト
sqlite3 /tmp/test.db "SELECT 1"

# パーミッションを修正
chmod 644 /path/to/database.db

🔧 完全なトラブルシューティングガイド: すべての問題の詳細な解決策については、docs/TROUBLESHOOTING.mdを参照してください。

🤝 コントリビューション

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

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

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

🔗 リンク

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